Beispiel #1
0
    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"
        ])
Beispiel #2
0
    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
Beispiel #4
0
    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",
            ]
        )
Beispiel #5
0
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()
Beispiel #6
0
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)
Beispiel #7
0
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()
Beispiel #8
0
 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(
    )
Beispiel #15
0
    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()
Beispiel #16
0
#!/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"
Beispiel #17
0
    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()
Beispiel #18
0
import sys
from pydoctor.driver import main

if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))
Beispiel #19
0
#!/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"