Module pdocs.api

This module defines the programmatic API that can be used to interact with pdocs to generate and view documentation from Python source code.

If you want to extend pdocs or use it directly from within Python - this is the place to start.

View Source
"""This module defines the programmatic API that can be used to interact with `pdocs`

   to generate and view documentation from Python source code.

   If you want to extend `pdocs` or use it directly from within Python - this is the place

   to start.

"""

import os

import pathlib

import sys

import tempfile

import webbrowser

import hug

import pdocs.extract

import pdocs.logo

import pdocs.render

import pdocs.static

from pdocs import defaults

def as_html(

    modules: list,

    output_dir: str = defaults.HTML_OUTPUT_DIRECTORY,

    overwrite: bool = False,

    external_links: bool = False,

    exclude_source: bool = False,

    link_prefix: str = "",

    template_dir: str = "",

) -> str:

    """Produces HTML formatted output into the specified output_dir.

    - *modules*: One or more python module names. These may be import paths resolvable in the

      current environment, or file paths to a Python module or package.

    - *output_dir*: The directory to output HTML files to.

    - *overwrite*: If set, will overwrites any existing files in the output location.

    - *external_links*: When set, identifiers to external modules are turned into links.

    - *exclude_source*: When set, source code will not be viewable in the generated HTML.

    - *link_prefix*: A prefix to use for every link in the generated documentation otherwise

      relative links will be used.

    - *template_dir*: Specify a directory containing override Mako templates.

    Returns the `output_dir` on success.

    """

    if template_dir:

        pdocs.render.tpl_lookup.directories.insert(0, template_dir)

    roots = _get_root_modules(modules)

    destination = _destination(output_dir, roots, overwrite)

    pdocs.static.html_out(

        destination,

        roots,

        external_links=external_links,

        source=not exclude_source,

        link_prefix=link_prefix,

    )

    return output_dir

def as_markdown(

    modules: list,

    output_dir: str = defaults.MARKDOWN_OUTPUT_DIRECTORY,

    overwrite: bool = False,

    exclude_source: bool = False,

    template_dir: str = "",

) -> str:

    """Produces Markdown formatted output into the specified output_dir.

    - *modules*: One or more python module names. These may be import paths resolvable in the

      current environment, or file paths to a Python module or package.

    - *output_dir*: The directory to output HTML files to.

    - *overwrite*: If set, will overwrites any existing files in the output location.

    - *exclude_source*: When set, source code will not be viewable in the generated Markdown.

    - *template_dir*: Specify a directory containing override Mako templates.

    Returns the `output_dir` on success.

    """

    if template_dir:

        pdocs.render.tpl_lookup.directories.insert(0, template_dir)

    roots = _get_root_modules(modules)

    destination = _destination(output_dir, roots, overwrite)

    pdocs.static.md_out(destination, roots, source=not exclude_source)

    return output_dir

def server(

    modules: list,

    external_links: bool = False,

    exclude_source: bool = False,

    link_prefix: str = "",

    template_dir: str = "",

    open_browser: bool = False,

    port: int = defaults.SERVER_PORT,

    host: str = defaults.SERVER_HOST,

) -> None:

    """Runs a development webserver enabling you to browse documentation locally.

    - *modules*: One or more python module names. These may be import paths resolvable in the

      current environment, or file paths to a Python module or package.

    - *external_links*: When set, identifiers to external modules are turned into links.

    - *exclude_source*: When set, source code will not be viewable in the generated HTML.

    - *link_prefix*: A prefix to use for every link in the generated documentation otherwise

      relative links will be used.

    - *template_dir*: Specify a directory containing override Mako templates.

    - *open_browser*: If true a browser will be opened pointing at the documentation server

    - *port*: The port to expose your documentation on (defaults to: `8000`)

    - *host*: The host to expose your documentation on (defaults to `"127.0.0.1"`)

    """

    with tempfile.TemporaryDirectory() as output_dir:

        as_html(

            modules,

            overwrite=True,

            output_dir=output_dir,

            external_links=external_links,

            template_dir=template_dir,

        )

        if len(modules) == 1:

            output_dir = os.path.join(output_dir, modules[0])

        api = hug.API("Doc Server")

        @hug.static("/", api=api)

        def my_static_dirs():  # pragma: no cover

            return (output_dir,)

        @hug.startup(api=api)

        def custom_startup(*args, **kwargs):  # pragma: no cover

            print(pdocs.logo.ascii_art)

            if open_browser:

                webbrowser.open_new(f"http://{host}:{port}")

        api.http.serve(host=host, port=port, no_documentation=True, display_intro=False)

def _get_root_modules(module_names):

    if not module_names:

        sys.exit("Please provide one or more modules")

    try:

        return [pdocs.extract.extract_module(module_name) for module_name in module_names]

    except pdocs.extract.ExtractError as error:

        sys.exit(str(error))

def _destination(directory, root_modules, overwrite):

    destination = pathlib.Path(directory)

    if not overwrite and pdocs.static.would_overwrite(destination, root_modules):

        sys.exit("Rendering would overwrite files, but --overwrite is not set")

    return destination

Functions

as_html
def (
    modules: list,
    output_dir: str = 'site',
    overwrite: bool = False,
    external_links: bool = False,
    exclude_source: bool = False,
    link_prefix: str = '',
    template_dir: str = ''
) -> str

Produces HTML formatted output into the specified output_dir.

  • modules: One or more python module names. These may be import paths resolvable in the current environment, or file paths to a Python module or package.
  • output_dir: The directory to output HTML files to.
  • overwrite: If set, will overwrites any existing files in the output location.
  • external_links: When set, identifiers to external modules are turned into links.
  • exclude_source: When set, source code will not be viewable in the generated HTML.
  • link_prefix: A prefix to use for every link in the generated documentation otherwise relative links will be used.
  • template_dir: Specify a directory containing override Mako templates.

Returns the output_dir on success.

View Source
def as_html(

    modules: list,

    output_dir: str = defaults.HTML_OUTPUT_DIRECTORY,

    overwrite: bool = False,

    external_links: bool = False,

    exclude_source: bool = False,

    link_prefix: str = "",

    template_dir: str = "",

) -> str:

    """Produces HTML formatted output into the specified output_dir.

    - *modules*: One or more python module names. These may be import paths resolvable in the

      current environment, or file paths to a Python module or package.

    - *output_dir*: The directory to output HTML files to.

    - *overwrite*: If set, will overwrites any existing files in the output location.

    - *external_links*: When set, identifiers to external modules are turned into links.

    - *exclude_source*: When set, source code will not be viewable in the generated HTML.

    - *link_prefix*: A prefix to use for every link in the generated documentation otherwise

      relative links will be used.

    - *template_dir*: Specify a directory containing override Mako templates.

    Returns the `output_dir` on success.

    """

    if template_dir:

        pdocs.render.tpl_lookup.directories.insert(0, template_dir)

    roots = _get_root_modules(modules)

    destination = _destination(output_dir, roots, overwrite)

    pdocs.static.html_out(

        destination,

        roots,

        external_links=external_links,

        source=not exclude_source,

        link_prefix=link_prefix,

    )

    return output_dir
as_markdown
def (
    modules: list,
    output_dir: str = 'docs',
    overwrite: bool = False,
    exclude_source: bool = False,
    template_dir: str = ''
) -> str

Produces Markdown formatted output into the specified output_dir.

  • modules: One or more python module names. These may be import paths resolvable in the current environment, or file paths to a Python module or package.
  • output_dir: The directory to output HTML files to.
  • overwrite: If set, will overwrites any existing files in the output location.
  • exclude_source: When set, source code will not be viewable in the generated Markdown.
  • template_dir: Specify a directory containing override Mako templates.

Returns the output_dir on success.

View Source
def as_markdown(

    modules: list,

    output_dir: str = defaults.MARKDOWN_OUTPUT_DIRECTORY,

    overwrite: bool = False,

    exclude_source: bool = False,

    template_dir: str = "",

) -> str:

    """Produces Markdown formatted output into the specified output_dir.

    - *modules*: One or more python module names. These may be import paths resolvable in the

      current environment, or file paths to a Python module or package.

    - *output_dir*: The directory to output HTML files to.

    - *overwrite*: If set, will overwrites any existing files in the output location.

    - *exclude_source*: When set, source code will not be viewable in the generated Markdown.

    - *template_dir*: Specify a directory containing override Mako templates.

    Returns the `output_dir` on success.

    """

    if template_dir:

        pdocs.render.tpl_lookup.directories.insert(0, template_dir)

    roots = _get_root_modules(modules)

    destination = _destination(output_dir, roots, overwrite)

    pdocs.static.md_out(destination, roots, source=not exclude_source)

    return output_dir
server
def (
    modules: list,
    external_links: bool = False,
    exclude_source: bool = False,
    link_prefix: str = '',
    template_dir: str = '',
    open_browser: bool = False,
    port: int = 8080,
    host: str = '127.0.0.1'
) -> None

Runs a development webserver enabling you to browse documentation locally.

  • modules: One or more python module names. These may be import paths resolvable in the current environment, or file paths to a Python module or package.
  • external_links: When set, identifiers to external modules are turned into links.
  • exclude_source: When set, source code will not be viewable in the generated HTML.
  • link_prefix: A prefix to use for every link in the generated documentation otherwise relative links will be used.
  • template_dir: Specify a directory containing override Mako templates.
  • open_browser: If true a browser will be opened pointing at the documentation server
  • port: The port to expose your documentation on (defaults to: 8000)
  • host: The host to expose your documentation on (defaults to "127.0.0.1")
View Source
def server(

    modules: list,

    external_links: bool = False,

    exclude_source: bool = False,

    link_prefix: str = "",

    template_dir: str = "",

    open_browser: bool = False,

    port: int = defaults.SERVER_PORT,

    host: str = defaults.SERVER_HOST,

) -> None:

    """Runs a development webserver enabling you to browse documentation locally.

    - *modules*: One or more python module names. These may be import paths resolvable in the

      current environment, or file paths to a Python module or package.

    - *external_links*: When set, identifiers to external modules are turned into links.

    - *exclude_source*: When set, source code will not be viewable in the generated HTML.

    - *link_prefix*: A prefix to use for every link in the generated documentation otherwise

      relative links will be used.

    - *template_dir*: Specify a directory containing override Mako templates.

    - *open_browser*: If true a browser will be opened pointing at the documentation server

    - *port*: The port to expose your documentation on (defaults to: `8000`)

    - *host*: The host to expose your documentation on (defaults to `"127.0.0.1"`)

    """

    with tempfile.TemporaryDirectory() as output_dir:

        as_html(

            modules,

            overwrite=True,

            output_dir=output_dir,

            external_links=external_links,

            template_dir=template_dir,

        )

        if len(modules) == 1:

            output_dir = os.path.join(output_dir, modules[0])

        api = hug.API("Doc Server")

        @hug.static("/", api=api)

        def my_static_dirs():  # pragma: no cover

            return (output_dir,)

        @hug.startup(api=api)

        def custom_startup(*args, **kwargs):  # pragma: no cover

            print(pdocs.logo.ascii_art)

            if open_browser:

                webbrowser.open_new(f"http://{host}:{port}")

        api.http.serve(host=host, port=port, no_documentation=True, display_intro=False)