def build(self, projectName, projectURL, sourceURL, packagePath,
outputPath):
"""
Call pydoctor's entry point with options which will generate HTML
documentation for the specified package's API.
@type projectName: C{str}
@param projectName: The name of the package for which to generate
documentation.
@type projectURL: C{str}
@param projectURL: The location (probably an HTTP URL) of the project
on the web.
@type sourceURL: C{str}
@param sourceURL: The location (probably an HTTP URL) of the root of
the source browser for the project.
@type packagePath: L{FilePath}
@param packagePath: The path to the top-level of the package named by
C{projectName}.
@type outputPath: L{FilePath}
@param outputPath: An existing directory to which the generated API
documentation will be written.
"""
from pydoctor.driver import main
main([
"--project-name", projectName, "--project-url", projectURL,
"--system-class", "pydoctor.twistedmodel.TwistedSystem",
"--project-base-dir",
packagePath.parent().path, "--html-viewsource-base", sourceURL,
"--add-package", packagePath.path, "--html-output",
outputPath.path, "--quiet", "--make-html"
])
def build(self, projectName, projectURL, sourceURL, packagePath,
outputPath):
"""
Call pydoctor's entry point with options which will generate HTML
documentation for the specified package's API.
@type projectName: C{str}
@param projectName: The name of the package for which to generate
documentation.
@type projectURL: C{str}
@param projectURL: The location (probably an HTTP URL) of the project
on the web.
@type sourceURL: C{str}
@param sourceURL: The location (probably an HTTP URL) of the root of
the source browser for the project.
@type packagePath: L{FilePath}
@param packagePath: The path to the top-level of the package named by
C{projectName}.
@type outputPath: L{FilePath}
@param outputPath: An existing directory to which the generated API
documentation will be written.
"""
intersphinxes = []
for intersphinx in intersphinxURLs:
intersphinxes.append("--intersphinx")
intersphinxes.append(intersphinx)
from pydoctor.driver import main # type: ignore[import]
templatesPath = FilePath(__file__).parent().child("_pydoctortemplates")
args = [
"--project-name",
projectName,
"--project-url",
projectURL,
"--system-class",
"twisted.python._pydoctor.TwistedSystem",
"--project-base-dir",
packagePath.parent().path,
"--template-dir",
templatesPath.path,
"--html-viewsource-base",
sourceURL,
"--html-output",
outputPath.path,
"--quiet",
"--make-html",
"--warnings-as-errors",
] + intersphinxes
args.append(packagePath.path)
main(args)
def test_main_source_outside_basedir(capsys: CapSys) -> None:
"""
If a --project-base-dir is given, all package and module paths must
be located inside that base directory.
"""
with raises(SystemExit):
driver.main(args=[
'--project-base-dir=docs', 'pydoctor/test/testpackages/basic/'
])
assert "Source path lies outside base directory:" in capsys.readouterr(
).err
def build(self, projectName, projectURL, sourceURL, packagePath, outputPath):
"""
Call pydoctor's entry point with options which will generate HTML
documentation for the specified package's API.
@type projectName: C{str}
@param projectName: The name of the package for which to generate
documentation.
@type projectURL: C{str}
@param projectURL: The location (probably an HTTP URL) of the project
on the web.
@type sourceURL: C{str}
@param sourceURL: The location (probably an HTTP URL) of the root of
the source browser for the project.
@type packagePath: L{FilePath}
@param packagePath: The path to the top-level of the package named by
C{projectName}.
@type outputPath: L{FilePath}
@param outputPath: An existing directory to which the generated API
documentation will be written.
"""
from pydoctor.driver import main
main(
[
"--project-name",
projectName,
"--project-url",
projectURL,
"--system-class",
"pydoctor.twistedmodel.TwistedSystem",
"--project-base-dir",
packagePath.parent().path,
"--html-viewsource-base",
sourceURL,
"--add-package",
packagePath.path,
"--html-output",
outputPath.path,
"--html-write-function-pages",
"--quiet",
"--make-html",
]
)
def geterrtext(*options):
options = list(options)
se = sys.stderr
f = cStringIO.StringIO()
print options
sys.stderr = f
try:
try:
driver.main(options)
except SystemExit:
pass
else:
assert False, "did not fail"
finally:
sys.stderr = se
return f.getvalue()
def _run_pydoctor(name: str, arguments: Sequence[str]) -> None:
"""
Call pydoctor with arguments.
@param name: A human-readable description of this pydoctor build.
@param arguments: Command line arguments used to call pydoctor.
"""
logger.info(f"Building '{name}' pydoctor API docs as:")
logger.info('\n'.join(arguments))
with StringIO() as stream:
with redirect_stdout(stream):
main(args=arguments)
for line in stream.getvalue().splitlines():
logger.warning(line)
def geterrtext(*options):
options = list(options)
se = sys.stderr
f = cStringIO.StringIO()
print options
sys.stderr = f
try:
try:
driver.main(options)
except SystemExit:
pass
else:
assert False, "did not fail"
finally:
sys.stderr = se
return f.getvalue()
def run(self):
"""build API documentation."""
# if options.build_dir:
# docs.builddir = options.build_dir
if not path.exists(docs.builddir):
os.mkdir(docs.builddir)
docs.state_is_api = True
from pydoctor.driver import main
argv = [
'--html-output=%s/apidocs' % docs.builddir, '--project-name=fixture',
'--docformat=restructuredtext',
'--project-url=http://code.google.com/p/fixture/', '--make-html',
'--add-package=fixture', '--verbose', '--verbose']
sys.argv[0] = ['pydoctor'] # can't remember why
main(argv)
def geterrtext(*options: str) -> str:
"""
Run CLI with options and return the output triggered by system exit.
"""
se = sys.stderr
f = StringIO()
print(options)
sys.stderr = f
try:
try:
driver.main(list(options))
except SystemExit:
pass
else:
assert False, "did not fail"
finally:
sys.stderr = se
return f.getvalue()
def test_main_project_name_guess(capsys: CapSys) -> None:
"""
When no project name is provided in the CLI arguments, a default name
is used and logged.
"""
exit_code = driver.main(
args=['-v', '--testing', 'pydoctor/test/testpackages/basic/'])
assert exit_code == 0
assert "Guessing 'basic' for project name." in capsys.readouterr().out
def test_main_project_name_option(capsys: CapSys) -> None:
"""
When a project name is provided in the CLI arguments nothing is logged.
"""
exit_code = driver.main(args=[
'-v', '--testing', '--project-name=some-name',
'pydoctor/test/testpackages/basic/'
])
assert exit_code == 0
assert 'Guessing ' not in capsys.readouterr().out
def test_main_symlinked_paths(tmp_path: Path) -> None:
"""
The project base directory and package/module directories are normalized
in the same way, such that System.setSourceHref() can call Path.relative_to()
on them.
"""
link = tmp_path / 'src'
link.symlink_to(Path.cwd(), target_is_directory=True)
exit_code = driver.main(args=[
'--project-base-dir=.', '--html-viewsource-base=http://example.com',
f'{link}/pydoctor/test/testpackages/basic/'
])
assert exit_code == 0
def test_main_return_non_zero_on_warnings() -> None:
"""
When `-W` is used it returns 3 as exit code when there are warnings.
"""
stream = StringIO()
with redirect_stdout(stream):
exit_code = driver.main(args=[
'-W', '--html-writer=pydoctor.test.InMemoryWriter',
'pydoctor/test/testpackages/report_trigger/'
])
assert exit_code == 3
assert "__init__.py:8: Unknown field 'bad_field'" in stream.getvalue()
assert 'report_module.py:9: Cannot find link target for "BadLink"' in stream.getvalue(
)
def test_make_intersphix(tmp_path: Path) -> None:
"""
--make-intersphinx without --make-html will only produce the Sphinx inventory object.
This is also an integration test for the Sphinx inventory writer.
"""
inventory = tmp_path / 'objects.inv'
exit_code = driver.main(args=[
'--project-base-dir=.', '--make-intersphinx',
'--project-name=acme-lib', '--project-version=20.12.0-dev123',
'--html-output',
str(tmp_path), 'pydoctor/test/testpackages/basic/'
])
assert exit_code == 0
# No other files are created, other than the inventory.
assert [p.name for p in tmp_path.iterdir()] == ['objects.inv']
assert inventory.is_file()
assert b'Project: acme-lib\n# Version: 20.12.0-dev123\n' in inventory.read_bytes(
)
def build(self, projectName, projectURL, sourceURL, packagePath,
outputPath):
"""
Call pydoctor's entry point with options which will generate HTML
documentation for the specified package's API.
@type projectName: C{str}
@param projectName: The name of the package for which to generate
documentation.
@type projectURL: C{str}
@param projectURL: The location (probably an HTTP URL) of the project
on the web.
@type sourceURL: C{str}
@param sourceURL: The location (probably an HTTP URL) of the root of
the source browser for the project.
@type packagePath: L{FilePath}
@param packagePath: The path to the top-level of the package named by
C{projectName}.
@type outputPath: L{FilePath}
@param outputPath: An existing directory to which the generated API
documentation will be written.
"""
intersphinxes = []
for intersphinx in intersphinxURLs:
intersphinxes.append("--intersphinx")
intersphinxes.append(intersphinx)
# Super awful monkeypatch that will selectively use our templates.
from pydoctor.templatewriter import util
originalTemplatefile = util.templatefile
def templatefile(filename):
if filename in ["summary.html", "index.html", "common.html"]:
twistedPythonDir = FilePath(__file__).parent()
templatesDir = twistedPythonDir.child("_pydoctortemplates")
return templatesDir.child(filename).path
else:
return originalTemplatefile(filename)
monkeyPatch = MonkeyPatcher((util, "templatefile", templatefile))
monkeyPatch.patch()
from pydoctor.driver import main
args = [
u"--project-name",
projectName,
u"--project-url",
projectURL,
u"--system-class",
u"twisted.python._pydoctor.TwistedSystem",
u"--project-base-dir",
packagePath.parent().path,
u"--html-viewsource-base",
sourceURL,
u"--add-package",
packagePath.path,
u"--html-output",
outputPath.path,
u"--html-write-function-pages",
u"--quiet",
u"--make-html",
] + intersphinxes
args = [arg.encode("utf-8") for arg in args]
main(args)
monkeyPatch.restore()
#!/usr/bin/env python
'''
Pydoctor API Runner
---------------------
Using pkg_resources, we attempt to see if pydoctor is installed,
if so, we use its cli program to compile the documents
'''
try:
import sys, os, shutil
import pkg_resources
pkg_resources.require("pydoctor")
from pydoctor.driver import main
sys.argv = '''pydoctor.py --quiet
--project-name=Pymodbus
--project-url=http://code.google.com/p/pymodbus/
--add-package=../../../pymodbus
--html-output=html
--html-write-function-pages --make-html'''.split()
print "Building Pydoctor API Documentation"
main(sys.argv[1:])
if os.path.exists('../../../build'):
shutil.move("html", "../../../build/pydoctor")
except: print "Pydoctor unavailable...not building"
def build(self, projectName, projectURL, sourceURL, packagePath,
outputPath):
"""
Call pydoctor's entry point with options which will generate HTML
documentation for the specified package's API.
@type projectName: C{str}
@param projectName: The name of the package for which to generate
documentation.
@type projectURL: C{str}
@param projectURL: The location (probably an HTTP URL) of the project
on the web.
@type sourceURL: C{str}
@param sourceURL: The location (probably an HTTP URL) of the root of
the source browser for the project.
@type packagePath: L{FilePath}
@param packagePath: The path to the top-level of the package named by
C{projectName}.
@type outputPath: L{FilePath}
@param outputPath: An existing directory to which the generated API
documentation will be written.
"""
intersphinxes = []
for intersphinx in intersphinxURLs:
intersphinxes.append("--intersphinx")
intersphinxes.append(intersphinx)
# Super awful monkeypatch that will selectively use our templates.
from pydoctor.templatewriter import util
originalTemplatefile = util.templatefile
def templatefile(filename):
if filename in ["summary.html", "index.html", "common.html"]:
twistedPythonDir = FilePath(__file__).parent()
templatesDir = twistedPythonDir.child("_pydoctortemplates")
return templatesDir.child(filename).path
else:
return originalTemplatefile(filename)
monkeyPatch = MonkeyPatcher((util, "templatefile", templatefile))
monkeyPatch.patch()
from pydoctor.driver import main
args = [u"--project-name", projectName,
u"--project-url", projectURL,
u"--system-class", u"twisted.python._pydoctor.TwistedSystem",
u"--project-base-dir", packagePath.parent().path,
u"--html-viewsource-base", sourceURL,
u"--add-package", packagePath.path,
u"--html-output", outputPath.path,
u"--html-write-function-pages", u"--quiet", u"--make-html",
] + intersphinxes
args = [arg.encode("utf-8") for arg in args]
main(args)
monkeyPatch.restore()
import sys
from pydoctor.driver import main
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
#!/usr/bin/env python
'''
Pydoctor API Runner
---------------------
Using pkg_resources, we attempt to see if pydoctor is installed,
if so, we use its cli program to compile the documents
'''
try:
import sys, os, shutil
import pkg_resources
pkg_resources.require("pydoctor")
from pydoctor.driver import main
sys.argv = '''pydoctor.py --quiet
--project-name=Pymodbus
--project-url=http://code.google.com/p/pymodbus/
--add-package=../../../pymodbus
--html-output=html
--html-write-function-pages --make-html'''.split()
print "Building Pydoctor API Documentation"
main(sys.argv[1:])
if os.path.exists('../../../build'):
shutil.move("html", "../../../build/pydoctor")
except:
print "Pydoctor unavailable...not building"
