def test_cli_warnings_on_error() -> None:
"""
The --warnings-as-errors option is disabled by default.
This is the test for the long form of the CLI option.
"""
options, args = driver.parse_args([])
assert options.warnings_as_errors == False
options, args = driver.parse_args(['--warnings-as-errors'])
assert options.warnings_as_errors == True
def run(self) -> List[nodes.Node]:
"""
Called by docutils each time the directive is found.
"""
stream = StringIO()
try:
with redirect_stdout(stream):
parse_args(['--help'])
except SystemExit:
# The stdlib --help handling triggers system exit.
pass
text = ['pydoctor --help'] + stream.getvalue().splitlines()[1:]
return [nodes.literal_block(text='\n'.join(text), language='text')]
def test_fetchIntersphinxInventories_content():
"""
Download and parse intersphinx inventories for each configured
intersphix.
"""
options, _ = parse_args([])
options.intersphinx = [
'http://sphinx/objects.inv',
'file:///twisted/index.inv',
]
url_content = {
'http://sphinx/objects.inv': zlib.compress(
'sphinx.module py:module -1 sp.html -'),
'file:///twisted/index.inv': zlib.compress(
'twisted.package py:module -1 tm.html -'),
}
sut = model.System(options=options)
log = []
sut.msg = lambda part, msg: log.append((part, msg))
# Patch url getter to avoid touching the network.
sut.intersphinx._getURL = lambda url: url_content[url]
sut.fetchIntersphinxInventories()
assert [] == log
assert (
'http://sphinx/sp.html' ==
sut.intersphinx.getLink('sphinx.module')
)
assert (
'file:///twisted/tm.html' ==
sut.intersphinx.getLink('twisted.package')
)
def __init__(self, options=None):
self.allobjects = {}
self.orderedallobjects = []
self.rootobjects = []
self.warnings = {}
self.packages = []
self.moresystems = []
self.subsystems = []
self.urlprefix = ''
if options:
self.options = options
else:
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.abbrevmapping = {}
self.projectname = 'my project'
self.epytextproblems = [
] # fullNames of objects that failed to epytext properly
self.verboselevel = 0
self.needsnl = False
self.once_msgs = set()
self.unprocessed_modules = set()
self.module_count = 0
self.processing_modules = []
self.buildtime = datetime.datetime.now()
# Once pickle support is removed, System should be
# initialized with project name so that we can reuse intersphinx instance for
# object.inv generation.
self.intersphinx = SphinxInventory(logger=self.msg,
project_name=self.projectname)
def __init__(self, options=None):
self.allobjects = {}
self.orderedallobjects = []
self.rootobjects = []
self.warnings = {}
self.packages = []
self.moresystems = []
self.subsystems = []
self.urlprefix = ''
if options:
self.options = options
else:
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.abbrevmapping = {}
self.projectname = 'my project'
self.epytextproblems = [] # fullNames of objects that failed to epytext properly
self.verboselevel = 0
self.needsnl = False
self.once_msgs = set()
self.unprocessed_modules = set()
self.module_count = 0
self.processing_modules = []
self.buildtime = datetime.datetime.now()
# Once pickle support is removed, System should be
# initialized with project name so that we can reuse intersphinx instance for
# object.inv generation.
self.intersphinx = SphinxInventory(logger=self.msg, project_name=self.projectname)
def on_build_finished(app: Sphinx, exception: Exception) -> None:
"""
Called when Sphinx build is done.
"""
if app.builder.name != 'html':
return
runs = app.config.pydoctor_args
placeholders = {
'outdir': app.outdir,
}
if not isinstance(runs, Mapping):
# We have a single pydoctor call
runs = {'main': runs}
for key, value in runs.items():
arguments = _get_arguments(value, placeholders)
options, _ = parse_args(arguments)
output_path = pathlib.Path(options.htmloutput)
sphinx_files = output_path.with_suffix('.sphinx_files')
temp_path = output_path.with_suffix('.pydoctor_temp')
shutil.rmtree(sphinx_files, ignore_errors=True)
output_path.rename(sphinx_files)
temp_path.rename(output_path)
def test_fetchIntersphinxInventories_content():
"""
Download and parse intersphinx inventories for each configured
intersphix.
"""
options, _ = parse_args([])
options.intersphinx = [
'http://sphinx/objects.inv',
'file:///twisted/index.inv',
]
url_content = {
'http://sphinx/objects.inv': zlib.compress(
'sphinx.module py:module -1 sp.html -'),
'file:///twisted/index.inv': zlib.compress(
'twisted.package py:module -1 tm.html -'),
}
sut = model.System(options=options)
log = []
sut.msg = lambda part, msg: log.append((part, msg))
# Patch url getter to avoid touching the network.
sut.intersphinx._getURL = lambda url: url_content[url]
sut.fetchIntersphinxInventories()
assert [] == log
assert (
'http://sphinx/sp.html' ==
sut.intersphinx.getLink('sphinx.module')
)
assert (
'file:///twisted/tm.html' ==
sut.intersphinx.getLink('twisted.package')
)
def __init__(self, options=None):
self.allobjects = OrderedDict()
self.rootobjects = []
self.warnings = {}
self.packages = []
if options:
self.options = options
else:
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.abbrevmapping = {}
self.projectname = 'my project'
self.docstring_syntax_errors = set()
"""FullNames of objects for which the docstring failed to parse."""
self.verboselevel = 0
self.needsnl = False
self.once_msgs = set()
self.unprocessed_modules = set()
self.module_count = 0
self.processing_modules = []
self.buildtime = datetime.datetime.now()
self.intersphinx = SphinxInventory(logger=self.msg)
def __init__(self, options: Optional[Values] = None):
self.allobjects: Dict[str, Documentable] = {}
self.rootobjects: List[Documentable] = []
self.violations = 0
"""The number of docstring problems found.
This is used to determine whether to fail the build when using
the --warnings-as-errors option, so it should only be increased
for problems that the user can fix.
"""
if options:
self.options = options
else:
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.projectname = 'my project'
self.docstring_syntax_errors: Set[str] = set()
"""FullNames of objects for which the docstring failed to parse."""
self.verboselevel = 0
self.needsnl = False
self.once_msgs: Set[Tuple[str, str]] = set()
self.unprocessed_modules: Set[Module] = set()
self.module_count = 0
self.processing_modules: List[str] = []
self.buildtime = datetime.datetime.now()
self.intersphinx = SphinxInventory(logger=self.msg)
def __init__(self, options=None):
self.allobjects = {}
self.orderedallobjects = []
self.rootobjects = []
self.warnings = {}
self.packages = []
if options:
self.options = options
else:
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.abbrevmapping = {}
self.projectname = 'my project'
self.epytextproblems = [
] # fullNames of objects that failed to epytext properly
self.verboselevel = 0
self.needsnl = False
self.once_msgs = set()
self.unprocessed_modules = set()
self.module_count = 0
self.processing_modules = []
self.buildtime = datetime.datetime.now()
self.intersphinx = SphinxInventory(logger=self.msg)
def test_projectbasedir():
"""
The --project-base-dir option should set the projectbasedirectory attribute
on the options object.
"""
value = "projbasedirvalue"
options, args = driver.parse_args(["--project-base-dir", value])
assert options.projectbasedirectory == value
def test_projectbasedir():
"""
The --project-base-dir option should set the projectbasedirectory attribute
on the options object.
"""
value = "projbasedirvalue"
options, args = driver.parse_args([
"--project-base-dir", value])
assert options.projectbasedirectory == value
def test_projectbasedir_relative() -> None:
"""
The --project-base-dir option, when given a relative path, should convert
that path to absolute and set it as the projectbasedirectory attribute on
the options object.
"""
relative = "projbasedirvalue"
options, args = driver.parse_args(["--project-base-dir", relative])
assert options.projectbasedirectory.is_absolute()
assert options.projectbasedirectory.name == relative
assert options.projectbasedirectory.parent == Path.cwd()
def test_fetchIntersphinxInventories_empty():
"""
Convert option to empty dict.
"""
options, _ = parse_args([])
options.intersphinx = []
sut = model.System(options=options)
sut.fetchIntersphinxInventories()
# Use internal state since I don't know how else to
# check for SphinxInventory state.
assert {} == sut.intersphinx._links
def test_fetchIntersphinxInventories_empty():
"""
Convert option to empty dict.
"""
options, _ = parse_args([])
options.intersphinx = []
sut = model.System(options=options)
sut.fetchIntersphinxInventories()
# Use internal state since I don't know how else to
# check for SphinxInventory state.
assert {} == sut.intersphinx._links
def test_projectbasedir_symlink(tmp_path: Path) -> None:
"""
The --project-base-dir option, when given a path containing a symbolic link,
should resolve the path to the target directory.
"""
target = tmp_path / 'target'
target.mkdir()
link = tmp_path / 'link'
link.symlink_to('target', target_is_directory=True)
assert link.samefile(target)
options, args = driver.parse_args(["--project-base-dir", str(link)])
assert options.projectbasedirectory.samefile(target)
assert options.projectbasedirectory.is_absolute()
def test_projectbasedir_absolute(tmp_path: Path) -> None:
"""
The --project-base-dir option, when given an absolute path, should set that
path as the projectbasedirectory attribute on the options object.
Previous versions of this test tried using non-existing paths and compared
the string representations, but that was unreliable, since the input path
might contain a symlink that will be resolved, such as "/home" on macOS.
Using L{Path.samefile()} is reliable, but requires an existing path.
"""
assert tmp_path.is_absolute()
options, args = driver.parse_args(["--project-base-dir", str(tmp_path)])
assert options.projectbasedirectory.samefile(tmp_path)
assert options.projectbasedirectory.is_absolute()
def on_builder_inited(app: Sphinx) -> None:
"""
Called to build the API documentation HTML files
and inject our own intersphinx inventory object.
"""
if app.builder.name != 'html':
return
rtd_version = 'latest'
if os.environ.get('READTHEDOCS', '') == 'True':
rtd_version = os.environ.get('READTHEDOCS_VERSION', 'latest')
config = app.config
if not config.pydoctor_args:
raise ConfigError("Missing 'pydoctor_args'.")
placeholders = {
'outdir': app.outdir,
}
runs = config.pydoctor_args
if not isinstance(runs, Mapping):
# We have a single pydoctor call
runs = {'main': runs}
pydoctor_url_path = config.pydoctor_url_path
if not isinstance(pydoctor_url_path, Mapping):
pydoctor_url_path = {'main': pydoctor_url_path}
for key, value in runs.items():
arguments = _get_arguments(value, placeholders)
options, _ = parse_args(arguments)
output_path = pathlib.Path(options.htmloutput)
temp_path = output_path.with_suffix('.pydoctor_temp')
# Update intersphinx_mapping.
url_path = pydoctor_url_path.get(key)
if url_path:
intersphinx_mapping = config.intersphinx_mapping
url = url_path.format(**{'rtd_version': rtd_version})
inv = (str(temp_path / 'objects.inv'), )
intersphinx_mapping[f'{key}-api-docs'] = (None, (url, inv))
# Build the API docs in temporary path.
shutil.rmtree(temp_path, ignore_errors=True)
_run_pydoctor(key, arguments)
output_path.rename(temp_path)
def __init__(self):
self.allobjects = {}
self.orderedallobjects = []
self.rootobjects = []
self.warnings = {}
self.packages = []
self.moresystems = []
self.subsystems = []
self.urlprefix = ''
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.abbrevmapping = {}
self.guessedprojectname = 'my project'
self.epytextproblems = [] # fullNames of objects that failed to epytext properly
self.verboselevel = 0
self.needsnl = False
self.once_msgs = set()
self.unprocessed_modules = set()
self.module_count = 0
self.processing_modules = []
self.buildtime = datetime.datetime.now()
def __init__(self):
self.allobjects = {}
self.orderedallobjects = []
self.rootobjects = []
self.warnings = {}
self.packages = []
self.moresystems = []
self.subsystems = []
self.urlprefix = ''
from pydoctor.driver import parse_args
self.options, _ = parse_args([])
self.options.verbosity = 3
self.abbrevmapping = {}
self.guessedprojectname = 'my project'
self.epytextproblems = [
] # fullNames of objects that failed to epytext properly
self.verboselevel = 0
self.needsnl = False
self.once_msgs = set()
self.unprocessed_modules = set()
self.module_count = 0
self.processing_modules = []
self.buildtime = datetime.datetime.now()
def test_fetchIntersphinxInventories_content() -> None:
"""
Download and parse intersphinx inventories for each configured
intersphix.
"""
options, _ = parse_args([])
options.intersphinx = [
'http://sphinx/objects.inv',
'file:///twisted/index.inv',
]
url_content = {
'http://sphinx/objects.inv':
zlib.compress(b'sphinx.module py:module -1 sp.html -'),
'file:///twisted/index.inv':
zlib.compress(b'twisted.package py:module -1 tm.html -'),
}
sut = model.System(options=options)
log = []
def log_msg(part: str, msg: str) -> None:
log.append((part, msg))
sut.msg = log_msg # type: ignore[assignment]
class Cache(CacheT):
"""Avoid touching the network."""
def get(self, url: str) -> bytes:
return url_content[url]
sut.fetchIntersphinxInventories(Cache())
assert [] == log
assert (
'http://sphinx/sp.html' == sut.intersphinx.getLink('sphinx.module'))
assert ('file:///twisted/tm.html' == sut.intersphinx.getLink(
'twisted.package'))
def test_project_version_default() -> None:
"""
When no --project-version is provided, it will default empty string.
"""
options, args = driver.parse_args([])
assert options.projectversion == ''
def test_project_version_string() -> None:
"""
--project-version can be passed as a simple string.
"""
options, args = driver.parse_args(['--project-version', '1.2.3.rc1'])
assert options.projectversion == '1.2.3.rc1'