venv-doc 0.1.0__py3-none-any.whl

venv_doc/__init__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2025, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""venv-doc package.
+
+Like `cargo doc` for Python venvs.
+"""
+
+from __future__ import annotations
+
+from venv_doc._internal.cli import get_parser, main
+
+__all__: list[str] = ["get_parser", "main"]

venv_doc/__main__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2025, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""Entry-point module, in case you use `python -m venv_doc`.
+
+Why does this file exist, and why `__main__`? For more info, read:
+
+- https://www.python.org/dev/peps/pep-0338/
+- https://docs.python.org/3/using/cmdline.html#cmdoption-m
+"""
+
+import sys
+
+from venv_doc._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

venv_doc/_internal/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2025, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

venv_doc/_internal/cli.py

@@ -0,0 +1,485 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2025, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# Why does this file exist, and why not put this in `__main__`?
+#
+# You might be tempted to import things from `__main__` later,
+# but that will cause problems: the code will get executed twice:
+#
+# - When you run `python -m venv_doc` python will execute
+#   `__main__.py` as a script. That means there won't be any
+#   `venv_doc.__main__` in `sys.modules`.
+# - When you import `__main__` it will get executed again (as a module) because
+#   there's no `venv_doc.__main__` in `sys.modules`.
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from subprocess import run
+from tempfile import TemporaryDirectory
+from textwrap import dedent
+from time import perf_counter
+from typing import Any, cast
+
+from griffe import (
+    Alias,
+    AliasResolutionError,
+    CyclicAliasError,
+    GriffeLoader,
+    Module,
+    Object,
+    Parser,
+    load_extensions,
+)
+from mkdocstrings import CollectionError
+from zensical import build, serve
+from zensical.compat import mkdocstrings as zensical_mkdocstrings
+from zensical.config import parse_config
+
+from venv_doc._internal import debug
+
+
+class _DebugInfo(argparse.Action):
+    def __init__(self, nargs: int | str | None = 0, **kwargs: Any) -> None:
+        super().__init__(nargs=nargs, **kwargs)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> None:  # noqa: ARG002
+        debug._print_debug_info()
+        sys.exit(0)
+
+
+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
+
+
+_VENV_INFO_SCRIPT = """\
+import json
+from importlib.metadata import distributions
+from importlib.util import find_spec
+from inspect import getmodulename
+from pathlib import Path
+
+package_candidates = set()
+for distribution in distributions():
+    top_level = distribution.read_text("top_level.txt")
+    if top_level:
+        package_candidates.update(top_level.split())
+    else:
+        for path in distribution.files or []:
+            name = path.parts[0]
+            package_candidates.add(getmodulename(name) or name)
+
+package_names = []
+package_paths = set()
+for package in package_candidates:
+    if package.startswith("_") or not package.isidentifier():
+        continue
+    spec = find_spec(package)
+    if spec is None:
+        continue
+    package_names.append(package)
+    if spec.submodule_search_locations:
+        package_paths.update(str(Path(path).parent) for path in spec.submodule_search_locations)
+    elif spec.origin:
+        package_paths.add(str(Path(spec.origin).parent))
+
+print(json.dumps({"packages": sorted(package_names), "paths": sorted(package_paths)}))
+"""
+
+
+def _venv_python(venv_path: Path) -> Path:
+    """Return the Python interpreter in a virtual environment."""
+    candidates = (
+        (venv_path / "Scripts" / "python.exe", venv_path / "Scripts" / "python")
+        if os.name == "nt"
+        else (venv_path / "bin" / "python",)
+    )
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    msg = f"Could not find a Python interpreter in {venv_path}"
+    raise FileNotFoundError(msg)
+
+
+def _venv_packages(python: Path) -> tuple[list[str], list[str]]:
+    """Return public packages and their import roots from a Python interpreter."""
+    result = run(  # noqa: S603
+        [str(python), "-c", _VENV_INFO_SCRIPT],
+        capture_output=True,
+        check=True,
+        encoding="utf8",
+    )
+    info = json.loads(result.stdout)
+    return info["packages"], info["paths"]
+
+
+def _public_modules(module: Module) -> list[Module]:
+    """Return the public modules below a module, in declaration order."""
+    modules = []
+    for member in module.members.values():
+        if member.is_alias:
+            continue
+        try:
+            if not member.is_module or not member.is_public:
+                continue
+        except AliasResolutionError:
+            continue
+        public_module = cast("Module", member)
+        modules.append(public_module)
+        modules.extend(_public_modules(public_module))
+    return modules
+
+
+def _is_rendered_member(member: Object | Alias) -> bool:
+    """Whether a member is rendered with the generated configuration."""
+    try:
+        return member.is_public
+    except (AliasResolutionError, CyclicAliasError):
+        return False
+
+
+def _preparse_docstrings(modules: list[Module]) -> int:
+    """Pre-parse docstrings that will be rendered on module pages."""
+    objects: list[Object | Alias] = list(modules)
+    seen_objects: set[int] = set()
+    seen_docstrings: set[int] = set()
+    parsed = 0
+
+    while objects:
+        obj = objects.pop()
+        try:
+            target = obj.final_target if isinstance(obj, Alias) else obj
+        except (AliasResolutionError, CyclicAliasError):
+            continue
+
+        object_id = id(target)
+        if object_id in seen_objects:
+            continue
+        seen_objects.add(object_id)
+
+        if target.docstring is not None:
+            docstring_id = id(target.docstring)
+            if docstring_id not in seen_docstrings:
+                _ = target.docstring.parsed
+                seen_docstrings.add(docstring_id)
+                parsed += 1
+
+        if target.is_module or target.is_class:
+            objects.extend(member for member in obj.all_members.values() if _is_rendered_member(member))
+
+    return parsed
+
+
+def _noop_mkdocstrings_reset() -> None:
+    """Keep the pre-loaded mkdocstrings handlers alive."""
+
+
+def _write_page(path: Path, identifier: str) -> None:
+    """Write an API documentation page for an identifier."""
+    path.write_text(
+        f"---\ntitle: {identifier}\n---\n\n::: {identifier}\n    options:\n        show_submodules: false\n",
+        encoding="utf8",
+    )
+
+
+def _get_python_handler(config_path: Path) -> Any:
+    """Return Zensical's shared Python handler for a documentation build."""
+    config = parse_config(str(config_path))
+    zensical_mkdocstrings.reset()
+    zensical_mkdocstrings.get_mkdocstrings_extension(
+        **config["plugins"]["mkdocstrings"]["config"],
+        config=config,
+    )
+    handlers = zensical_mkdocstrings.HANDLERS
+    return handlers.get_handler("python")  # ty:ignore[unresolved-attribute]
+
+
+def _load_packages(handler: Any, packages: list[str]) -> dict[str, Module]:
+    """Load packages into a Python handler's shared Griffe collections."""
+    options = handler.get_options({})
+    parser = Parser(options.docstring_style) if options.docstring_style else None
+    parser_options = asdict(options.docstring_options) if options.docstring_options is not None else None
+
+    extensions = handler.normalize_extension_paths(options.extensions)
+    loader = GriffeLoader(
+        extensions=load_extensions(*extensions),
+        search_paths=handler._paths,
+        docstring_parser=parser,
+        docstring_options=parser_options,  # ty:ignore[invalid-argument-type]
+        modules_collection=handler._modules_collection,
+        lines_collection=handler._lines_collection,
+        allow_inspection=options.allow_inspection,
+        force_inspection=options.force_inspection,
+    )
+
+    root_modules = {}
+    try:
+        for module in options.preload_modules:
+            if module not in handler._modules_collection:
+                loader.load(
+                    module,
+                    try_relative_path=False,
+                    find_stubs_package=options.find_stubs_package,
+                )
+
+        for package in packages:
+            if package not in handler._modules_collection:
+                loader.load(
+                    package,
+                    try_relative_path=False,
+                    find_stubs_package=options.find_stubs_package,
+                )
+            root_modules[package] = cast("Module", handler._modules_collection[package])
+    except ImportError as error:
+        raise CollectionError(str(error)) from error
+
+    loader.resolve_aliases(
+        implicit=False,
+        external=handler.config.load_external_modules,
+    )
+    return root_modules
+
+
+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

venv_doc/_internal/debug.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2025, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+
+
+@dataclass
+class _Variable:
+    """Dataclass describing an environment variable."""
+
+    name: str
+    """Variable name."""
+    value: str
+    """Variable value."""
+
+
+@dataclass
+class _Package:
+    """Dataclass describing a Python package."""
+
+    name: str
+    """Package name."""
+    version: str
+    """Package version."""
+
+
+@dataclass
+class _Environment:
+    """Dataclass to store environment information."""
+
+    interpreter_name: str
+    """Python interpreter name."""
+    interpreter_version: str
+    """Python interpreter version."""
+    interpreter_path: str
+    """Path to Python executable."""
+    platform: str
+    """Operating System."""
+    packages: list[_Package]
+    """Installed packages."""
+    variables: list[_Variable]
+    """Environment variables."""
+
+
+def _interpreter_name_version() -> tuple[str, str]:
+    if hasattr(sys, "implementation"):
+        impl = sys.implementation.version
+        version = f"{impl.major}.{impl.minor}.{impl.micro}"
+        kind = impl.releaselevel
+        if kind != "final":
+            version += kind[0] + str(impl.serial)
+        return sys.implementation.name, version
+    return "", "0.0.0"
+
+
+def _get_version(dist: str = "venv-doc") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+def _get_debug_info() -> _Environment:
+    """Get debug/environment information.
+
+    Returns:
+        Environment information.
+    """
+    py_name, py_version = _interpreter_name_version()
+    packages = ["venv-doc"]
+    variables = ["PYTHONPATH", *[var for var in os.environ if var.startswith("VENV_DOC")]]
+    return _Environment(
+        interpreter_name=py_name,
+        interpreter_version=py_version,
+        interpreter_path=sys.executable,
+        platform=platform.platform(),
+        variables=[_Variable(var, val) for var in variables if (val := os.getenv(var))],
+        packages=[_Package(pkg, _get_version(pkg)) for pkg in packages],
+    )
+
+
+def _print_debug_info() -> None:
+    """Print debug/environment information."""
+    info = _get_debug_info()
+    print(f"- __System__: {info.platform}")
+    print(f"- __Python__: {info.interpreter_name} {info.interpreter_version} ({info.interpreter_path})")
+    print("- __Environment variables__:")
+    for var in info.variables:
+        print(f"  - `{var.name}`: `{var.value}`")
+    print("- __Installed packages__:")
+    for pkg in info.packages:
+        print(f"  - `{pkg.name}` v{pkg.version}")
+
+
+if __name__ == "__main__":
+    _print_debug_info()

venv_doc/_internal/sphinx_roles.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: ISC
+#
+# ISC License
+#
+# Copyright (c) 2025, Timothée Mazzucotelli and contributors
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE
+# USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from __future__ import annotations
+
+from re import fullmatch
+from typing import TYPE_CHECKING
+from xml.etree.ElementTree import Element
+
+from markdown.extensions import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+if TYPE_CHECKING:
+    from re import Match
+
+    from markdown import Markdown
+
+
+_PYTHON_ROLES = "attr|class|const|data|deco|exc|func|meth|mod|obj|type"
+"""Python-domain cross-reference roles supported by Sphinx."""
+
+_SPHINX_ROLE_RE = rf"(?<![\w`]):(?:py:)?(?P<role>{_PYTHON_ROLES}):`(?P<content>[^`\n]+)`(?!`)"
+"""Match a supported short or qualified Python-domain Sphinx role."""
+
+_PYTHON_IDENTIFIER_RE = r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*"
+"""Match the dotted Python object identifiers that mkdocs-autorefs can resolve."""
+
+_EXPLICIT_TITLE_RE = r"(?P<title>.+?)\s*<(?P<target>[^<>]+)>"
+"""Match Sphinx's ``title <target>`` cross-reference syntax."""
+
+
+class _SphinxRoleInlineProcessor(InlineProcessor):
+    """Turn supported Python-domain Sphinx roles into mkdocs-autorefs markers."""
+
+    def handleMatch(self, m: Match[str], data: str) -> tuple[Element, int, int]:  # noqa: ARG002,N802
+        """Create an ``autoref`` element for a Sphinx role where possible."""
+        role = m.group("role")
+        content = m.group("content")
+
+        # ``!`` explicitly disables linking in Sphinx. It must not become an
+        # autoref marker because a resolvable marker would create a link again.
+        if content.startswith("!"):
+            element = Element("code")
+            element.text = content[1:]
+            return element, m.start(0), m.end(0)
+
+        explicit_title = fullmatch(_EXPLICIT_TITLE_RE, content)
+        if explicit_title:
+            title = explicit_title.group("title")
+            identifier = explicit_title.group("target")
+        else:
+            title = content
+            identifier = content
+
+        # Sphinx uses a leading ``~`` only to shorten an implicit title, and a
+        # leading ``.`` only to affect lookup precedence. Autorefs has no
+        # equivalent contextual lookup, so resolve the unprefixed identifier.
+        if not explicit_title:
+            title = title.lstrip(".")
+            if title.startswith("~"):
+                title = title[1:].rsplit(".", maxsplit=1)[-1]
+        identifier = identifier.strip().lstrip("~.").removesuffix("()")
+
+        if not fullmatch(_PYTHON_IDENTIFIER_RE, identifier):
+            # Leave syntax that cannot name an mkdocs-autorefs object to
+            # Markdown's normal handling rather than making an invalid marker.
+            element = Element("code")
+            element.text = content
+            return element, m.start(0), m.end(0)
+
+        if role == "deco":
+            title = f"@{title}"
+
+        element = Element("autoref", {"identifier": identifier})
+        element.text = title
+        return element, m.start(0), m.end(0)
+
+
+class _SphinxRolesExtension(Extension):
+    """Convert Python-domain Sphinx roles to auto-references."""
+
+    name = "venv-doc-sphinx-roles"
+
+    def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802
+        """Register the role processor before Markdown's code-span processor."""
+        md.inlinePatterns.register(
+            _SphinxRoleInlineProcessor(_SPHINX_ROLE_RE, md),
+            self.name,
+            priority=191,
+        )

venv_doc-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: venv-doc
+Version: 0.1.0
+Summary: Like `cargo doc` for Python venvs.
+Author-Email: Timothée Mazzucotelli <dev@pawamoy.fr>
+License-Expression: ISC
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Project-URL: Homepage, https://pawamoy.github.io/venv-doc
+Project-URL: Documentation, https://pawamoy.github.io/venv-doc
+Project-URL: Changelog, https://pawamoy.github.io/venv-doc/changelog
+Project-URL: Repository, https://github.com/pawamoy/venv-doc
+Project-URL: Issues, https://github.com/pawamoy/venv-doc/issues
+Project-URL: Discussions, https://github.com/pawamoy/venv-doc/discussions
+Project-URL: Gitter, https://gitter.im/venv-doc/community
+Project-URL: Funding, https://github.com/sponsors/pawamoy
+Requires-Python: >=3.11
+Requires-Dist: griffe>=2.2
+Requires-Dist: prune-source>=0.1
+Requires-Dist: markdown-pycon>=1.0
+Requires-Dist: mkdocstrings-python>=2.0
+Requires-Dist: zensical>=0.0.57
+Description-Content-Type: text/markdown
+
+# venv-doc
+
+[![ci](https://github.com/pawamoy/venv-doc/workflows/ci/badge.svg)](https://github.com/pawamoy/venv-doc/actions?query=workflow%3Aci)
+[![documentation](https://img.shields.io/badge/docs-zensical-FF9100.svg?style=flat)](https://pawamoy.github.io/venv-doc/)
+[![pypi version](https://img.shields.io/pypi/v/venv-doc.svg)](https://pypi.org/project/venv-doc/)
+[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#venv-doc:gitter.im)
+
+Like `cargo doc` for Python venvs.
+
+## Installation
+
+```bash
+pip install venv-doc
+```
+
+With [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install venv-doc
+```
+
+## Sponsors
+
+<!-- sponsors-start -->
+<!-- sponsors-end -->

venv_doc-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+venv_doc-0.1.0.dist-info/METADATA,sha256=5c8ssgSSRs_ondZki45DmRDfBm_O5e8W56CSaCbPcCQ,2276
+venv_doc-0.1.0.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
+venv_doc-0.1.0.dist-info/entry_points.txt,sha256=c6waGinuuxmqaM4LVxN7e5Wnks0PCE5ckU4YgmtJV00,59
+venv_doc-0.1.0.dist-info/licenses/LICENSE,sha256=FnCVYk610bj4MkIFuYhAXmhIBYKebHhVp2YWO-8rEVY,771
+venv_doc/__init__.py,sha256=aPwPGdcepJuu-3XUkyHNRjq2bZX0cyNgvpU1EdnyOR4,1027
+venv_doc/__main__.py,sha256=Tw8JJrqHjAxblqjNHvOhnFqcMyVovqWmiLs0E6Qw58E,1183
+venv_doc/_internal/__init__.py,sha256=FNcSqCgny9Z6h2ijJwSvekOi5ka7WWQFmAGC7rNkmJE,831
+venv_doc/_internal/cli.py,sha256=0ZJpGfpWsCHsLmA3x7GGzLxGObHFBFHx46NmAfnKHwM,16622
+venv_doc/_internal/debug.py,sha256=PQzUIM1YIe5_DvnPdNyLSLqgDpO55ByL1_MAot8ip1w,3644
+venv_doc/_internal/sphinx_roles.py,sha256=VpD9ZqBT9ByHXaP1U8za8aJIveVYNiccUUy6kbWQWpQ,4124
+venv_doc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+venv_doc-0.1.0.dist-info/RECORD,,

venv_doc-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.5.0)
+Root-Is-Purelib: true
+Tag: py3-none-any

venv_doc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+venv-doc = venv_doc:main
+
+[gui_scripts]
+

venv_doc-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, Timothée Mazzucotelli and contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.