from __future__ import annotations import argparse from pathlib import Path import platform import subprocess import sys import warnings import pdoc.doc import pdoc.extract import pdoc.render import pdoc.web if sys.stdout.isatty(): # pragma: no cover red = "\x1b[31m" yellow = "\x1b[33m" gray = "\x1b[2m" white = "\x1b[1m" default = "\x1b[0m" else: red = yellow = gray = white = default = "" parser = argparse.ArgumentParser( description="Automatically generate API docs for Python modules.", formatter_class=argparse.ArgumentDefaultsHelpFormatter, add_help=False, ) mainargs = parser.add_argument_group(f"{white}Main Arguments{default}") mainargs.add_argument( "modules", type=str, default=[], metavar="module", nargs="*", help='Python module names. These may be importable Python module names ("pdoc.doc") or file paths ("./pdoc/doc.py")' '. Exclude submodules by specifying a negative !regex pattern, e.g. "foo !foo.bar".', ) mainargs.add_argument( "-o", "--output-directory", metavar="DIR", type=Path, help="Write rendered documentation to the specified directory, don't start a webserver.", ) renderopts = parser.add_argument_group(f"{white}Customize Rendering{default}") renderopts.add_argument( "-d", "--docformat", type=str, default="restructuredtext", choices=("markdown", "google", "numpy", "restructuredtext"), help="The default docstring format. For non-Markdown formats, pdoc will first convert matching syntax elements to " "Markdown and then process everything as Markdown.", ) renderopts.add_argument( "--include-undocumented", action=argparse.BooleanOptionalAction, default=True, help="Show classes/functions/variables that do not have a docstring.", ) renderopts.add_argument( "-e", "--edit-url", action="append", type=str, default=[], metavar="module=url", help="A mapping between module names and URL prefixes, used to display an 'Edit' button. " "May be passed multiple times. " "Example: pdoc=https://github.com/mitmproxy/pdoc/blob/main/pdoc/", ) renderopts.add_argument( "--favicon", type=str, metavar="URL", help="Specify a custom favicon URL.", ) renderopts.add_argument( "--footer-text", type=str, metavar="TEXT", help="Custom text for the page footer, for example the project name and current version number.", ) renderopts.add_argument( "--logo", type=str, metavar="URL", help="Add a project logo image.", ) renderopts.add_argument( "--logo-link", type=str, metavar="URL", help="Optional URL the logo should point to.", ) renderopts.add_argument( "--math", action=argparse.BooleanOptionalAction, default=False, help="Include MathJax from a CDN to enable math formula rendering.", ) renderopts.add_argument( "--mermaid", action=argparse.BooleanOptionalAction, default=False, help="Include Mermaid.js from a CDN to enable Mermaid diagram rendering.", ) renderopts.add_argument( "--search", action=argparse.BooleanOptionalAction, default=True, help="Enable search functionality if multiple modules are documented.", ) renderopts.add_argument( "--show-source", action=argparse.BooleanOptionalAction, default=True, help='Display "View Source" buttons.', ) renderopts.add_argument( "-t", "--template-directory", metavar="DIR", type=Path, default=None, help="A directory containing Jinja2 templates to customize output. " "Alternatively, put your templates in $XDG_CONFIG_HOME/pdoc and pdoc will automatically find them.", ) miscargs = parser.add_argument_group(f"{white}Miscellaneous Options{default}") miscargs.add_argument( "-h", "--host", type=str, default="localhost", help="The host on which to run the HTTP server.", ) miscargs.add_argument( "-p", "--port", type=int, default=None, help="The port on which to run the HTTP server.", ) miscargs.add_argument( "-n", "--no-browser", action="store_true", help="Don't open a browser after the web server has started.", ) miscargs.add_argument("--help", action="help", help="Show this help message and exit.") miscargs.add_argument( "--version", action="store_true", default=argparse.SUPPRESS, help="Show version information and exit.", ) def cli(args: list[str] | None = None) -> None: """Command-line entry point""" opts = parser.parse_args(args) if getattr(opts, "version", False): print( f"pdoc: {get_dev_version()}\n" f"Python: {platform.python_version()}\n" f"Platform: {platform.platform()}" ) return if not opts.modules: parser.print_help() print( f"\n{red}Error: Please specify which files or modules you want to document.{default}" ) sys.exit(1) warnings.showwarning = _nicer_showwarning pdoc.render.configure( docformat=opts.docformat, include_undocumented=opts.include_undocumented, edit_url_map=dict(x.split("=", 1) for x in opts.edit_url), favicon=opts.favicon, footer_text=opts.footer_text, logo=opts.logo, logo_link=opts.logo_link, math=opts.math, mermaid=opts.mermaid, search=opts.search, show_source=opts.show_source, template_directory=opts.template_directory, ) if opts.output_directory: pdoc.pdoc( *opts.modules, output_directory=opts.output_directory, ) return else: try: try: httpd = pdoc.web.DocServer((opts.host, opts.port or 8080), opts.modules) except OSError: # Couldn't bind, let's try again with a random port. httpd = pdoc.web.DocServer((opts.host, opts.port or 0), opts.modules) except OSError as e: print( f"{red}Cannot start web server on {opts.host}:{opts.port}: {e}{default}" ) sys.exit(1) with httpd: url = f"http://{opts.host}:{httpd.server_port}" print(f"pdoc server ready at {url}") if not opts.no_browser: pdoc.web.open_browser(url) try: httpd.serve_forever() except KeyboardInterrupt: httpd.server_close() return def get_dev_version() -> str: """ Return a detailed version string, sourced either from VERSION or obtained dynamically using git. """ pdoc_version = pdoc.__version__ here = Path(__file__).parent try: # pragma: no cover # Check that we're in the pdoc repository: # 60665024af9af2cda4229e91b4d15f2359a4a3dd is the first pdoc commit. subprocess.run( ["git", "cat-file", "-e", "60665024af9af2cda4229e91b4d15f2359a4a3dd"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, cwd=here, check=True, ) git_describe = subprocess.check_output( ["git", "describe", "--tags", "--long"], stderr=subprocess.STDOUT, cwd=here, ) last_tag, tag_dist_str, commit = git_describe.decode().strip().rsplit("-", 2) commit = commit.lstrip("g")[:7] tag_dist = int(tag_dist_str) except Exception: # pragma: no cover pass else: # Add commit info for non-tagged releases if tag_dist > 0: # pragma: no cover pdoc_version += f" (+{tag_dist}, commit {commit})" return pdoc_version def _nicer_showwarning(message, category, filename, lineno, file=None, line=None): """A replacement for `warnings.showwarning` that renders warnings in a more visually pleasing way.""" if category is UserWarning: print( f"{yellow}Warn:{default} {message} {gray}({filename}:{lineno}){default}", file=sys.stderr, ) elif category is RuntimeWarning: print( f"{yellow}Warn:{default} {message}", file=sys.stderr, ) else: print( f"{yellow}{category.__name__}:{default} {message} {gray}({filename}:{lineno}){default}", file=sys.stderr, ) if __name__ == "__main__": # pragma: no cover cli()