venv_doc ¤

def get_parser() -> argparse.ArgumentParser:
    """Return the CLI argument parser.

    Returns:
        An argparse parser.
    """
    parser = argparse.ArgumentParser(prog="venv-doc")
    parser.add_argument(
        "-V",
        "--version",
        action="version",
        version=f"%(prog)s {debug._get_version()}",
    )
    parser.add_argument(
        "--debug-info",
        action=_DebugInfo,
        help="Print debug information.",
    )
    parser.add_argument(
        "--self",
        action="store_true",
        help="Document packages from the environment running venv-doc instead of .venv.",
    )
    subparsers = parser.add_subparsers(dest="command", required=True)

    build_parser = subparsers.add_parser("build", help="Build the documentation.")
    build_parser.add_argument(
        "-c",
        "--clean",
        action="store_true",
        help="Clean cache.",
    )
    build_parser.add_argument(
        "-s",
        "--strict",
        action="store_true",
        help="Enable strict mode - abort the build on warnings.",
    )

    serve_parser = subparsers.add_parser(
        "serve",
        help="Build and serve the documentation.",
    )
    serve_parser.add_argument(
        "-a",
        "--dev-addr",
        metavar="<IP:PORT>",
        help="IP address and port (default: localhost:8000).",
    )
    serve_parser.add_argument(
        "-o",
        "--open",
        action="store_true",
        help="Open preview in default browser.",
    )
    serve_parser.add_argument(
        "-s",
        "--strict",
        action="store_true",
        help="Strict mode (currently unsupported).",
    )
    return parser

def main(args: list[str] | None = None) -> int:
    """Run the main program.

    This function is executed when you type `venv-doc` or `python -m venv_doc`.

    Parameters:
        args: Arguments passed from the command line.

    Returns:
        An exit code.
    """
    parsed_args = get_parser().parse_args(args)
    python = Path(sys.executable) if parsed_args.self else _venv_python(Path(".venv"))
    packages, package_paths = _venv_packages(python)

    with TemporaryDirectory() as tmpdir:
        tmppath = Path(tmpdir)
        tmppath.joinpath("docs").mkdir()
        config = dedent(
            f"""\
            [project]
            site_name = "API docs"
            nav = [
                {{ "API docs" = [
                    "index.md",
                    # {{packages}}
                ] }},
            ]
            validation = false

            [project.theme]
            features = [
                "announce.dismiss",
                "content.action.edit",
                "content.action.view",
                "content.code.annotate",
                "content.code.copy",
                "content.tooltips",
                "navigation.footer",
                "navigation.indexes",
                "navigation.instant.preview",
                "navigation.path",
                "navigation.top",
                "search.highlight",
                "search.suggest",
                "toc.follow",
            ]

            [[project.theme.palette]]
            media = "(prefers-color-scheme)"
            toggle.icon = "material/brightness-auto"
            toggle.name = "Switch to light mode"

            [[project.theme.palette]]
            media = "(prefers-color-scheme: light)"
            scheme = "default"
            primary = "teal"
            accent = "purple"
            toggle.icon = "material/weather-sunny"
            toggle.name = "Switch to dark mode"

            [[project.theme.palette]]
            media = "(prefers-color-scheme: dark)"
            scheme = "slate"
            primary = "black"
            accent = "lime"
            toggle.icon = "material/weather-night"
            toggle.name = "Switch to system preference"

            [project.markdown_extensions.toc]
            permalink = true

            [project.markdown_extensions]
            pycon = {{}}
            "venv_doc._internal.sphinx_roles:_SphinxRolesExtension" = {{}}

            [project.plugins.mkdocstrings.handlers.python]
            inventories = ["https://docs.python.org/3/objects.inv"]
            paths = {json.dumps(package_paths)}

            [project.plugins.mkdocstrings.handlers.python.options]
            docstring_options = {{
                per_style_options = {{
                    google = {{ warnings = false, ignore_init_summary = true }},
                    numpy = {{ warnings = false, ignore_init_summary = true }},
                    sphinx = {{ warnings = false }},
                }}
            }}
            docstring_section_style = "list"
            docstring_style = "auto"
            filters = "public"
            heading_level = 1
            inherited_members = true
            merge_init_into_class = true
            scoped_crossrefs = false
            separate_signature = true
            show_if_no_docstring = true
            show_root_heading = true
            show_root_full_path = false
            show_signature_annotations = true
            show_source = false
            show_submodules = false
            show_symbol_type_heading = true
            show_symbol_type_toc = true
            signature_crossrefs = true
            summary = true
            """,
        )
        config_path = tmppath.joinpath("zensical.toml")
        config_path.write_text(config, encoding="utf8")
        tmppath.joinpath("docs", "index.md").write_text(
            "# API docs\n\nSelect a package from the navigation to view its API reference.\n",
            encoding="utf8",
        )
        handler = _get_python_handler(config_path)
        root_modules = _load_packages(handler, packages)
        package_modules = {}
        documented_modules = []
        for package, root_module in root_modules.items():
            package_modules[package] = _public_modules(root_module)
            documented_modules.append(root_module)
            documented_modules.extend(package_modules[package])
            _write_page(tmppath.joinpath("docs", f"{package}.md"), package)
            for module in package_modules[package]:
                _write_page(tmppath.joinpath("docs", f"{module.path}.md"), module.path)

        nav = ",\n                    ".join(
            "{ "
            + json.dumps(package)
            + " = [\n                        "
            + json.dumps(f"{package}.md")
            + ",\n                        "
            + ",\n                        ".join(
                f"{{ {json.dumps(module.path)} = {json.dumps(f'{module.path}.md')} }}" for module in modules
            )
            + "\n                    ] }"
            for package, modules in package_modules.items()
        )
        config_path.write_text(config.replace("# {packages}", nav), encoding="utf8")
        started = perf_counter()
        parsed_docstrings = _preparse_docstrings(documented_modules)
        print(f"Pre-parsed {parsed_docstrings:,} docstrings in {perf_counter() - started:.2f}s", flush=True)
        reset_mkdocstrings = zensical_mkdocstrings.reset
        zensical_mkdocstrings.reset = _noop_mkdocstrings_reset  # ty:ignore[invalid-assignment]
        try:
            if parsed_args.command == "build":
                build(
                    str(config_path),
                    {"clean": parsed_args.clean, "strict": parsed_args.strict},
                )
            else:
                serve(
                    str(config_path),
                    {
                        "dev_addr": parsed_args.dev_addr,
                        "open": parsed_args.open,
                        "strict": parsed_args.strict,
                    },
                )
        finally:
            zensical_mkdocstrings.reset = reset_mkdocstrings

    return 0