doc-zero 0.1.1__py3-none-any.whl

doc0/__init__.py

@@ -0,0 +1,9 @@
+"""
+Base core module for the doc0 package.
+"""
+
+from .base import Doc0
+from .module import Module, ModuleSpec
+from .pyproject import PyProject
+
+__all__ = ["Doc0", "Module", "PyProject", "ModuleSpec"]

doc0/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

doc0/base.py

@@ -0,0 +1,445 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass, field
+from importlib.metadata import version as module_version
+from logging import getLogger
+from pathlib import Path
+from typing import Any, Iterable, Iterator, TypedDict
+
+from .module import Module
+from .pyproject import PyProject
+from .util import first_existing
+
+type ModuleName = str
+
+NOT_GIVEN: Any = object()
+COPYRIGHT_RE = re.compile(
+    r"[cC]opyright\s+(?:\(c\)\s+)?(?P<year>\d+)\s*(:?,?\s+(?P<author>[^\n]+))?"
+)
+DEFAULT_EXTENSIONS = [
+    "sphinx.ext.autodoc",
+    "sphinx_mdinclude",
+    # "myst_parser",
+]
+SPHINX_THEME_ALIASES = {
+    "rtd": "sphinx_rtd_theme",
+    "readthedocs": "sphinx_rtd_theme",
+    "default": "alabaster",
+}
+READTHEDOCS_TEMPLATE = """
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+"""
+
+log = getLogger(__name__)
+
+
+@dataclass
+class Doc0:
+    """
+    The root type representing the documentation of your project.
+    """
+
+    #: The pyproject.toml file for the project.
+    pyproject: PyProject
+
+    #: Base location for the documentation assets
+    doc_root: Path
+
+    #: The theme to use for the documentation.
+    theme: str
+
+    @classmethod
+    def load(
+        cls,
+        root: Path | None = None,
+        /,
+        *,
+        theme: str | None = None,
+        docs: str = "docs",
+    ) -> Doc0:
+        """
+        Load project in the given path.
+        """
+        root = root or Path.cwd()
+        pyproject = PyProject(root=root)
+
+        if theme is None:
+            theme = pyproject.get("tool.doc-zero.theme", default="default", type=str)
+
+        return Doc0(
+            doc_root=root / docs,
+            pyproject=pyproject,
+            theme=theme,
+        )
+
+    @property
+    def root(self) -> Path:
+        """
+        The root of the project.
+        """
+        return self.pyproject.root
+
+    def init(self) -> None:
+        """
+        Assure that the documentation is initialized.
+
+        Call .generate() if the documentation is not initialized.
+        """
+        self.doc_root.mkdir(parents=True, exist_ok=True)
+        (self.doc_root / "_static").mkdir(exist_ok=True)
+
+        # Write/overwrite docs/conf.py.
+        conf_path = self.doc_root / "conf.py"
+        conf = Conf.from_pyproject(self.pyproject, theme=self.theme)
+        conf_path.write_text(conf.render())
+
+        # Write docs/index.rst and docs/api/*
+        self.write_rst_files()
+        self.write_readme_md()
+
+        # Write the Read the Docs configuration file, if it doesn't exist.
+        rtd_path = self.root / ".readthedocs.yml"
+        if not rtd_path.exists():
+            rtd_path.write_text(READTHEDOCS_TEMPLATE)
+
+        # Write the requirements.txt file for Read the Docs, if it doesn't exist.
+        req_path = self.root / "docs" / "requirements.txt"
+        if not req_path.exists():
+            req_path.write_text(f"doc0>={module_version('doc0')}")
+
+    def build(self) -> None:
+        """
+        Build the documentation using sphinx.
+        """
+        from sphinx.cmd.build import main
+
+        self.init()
+        main([str(self.doc_root), str(self.root / "dist" / "docs")])
+
+    def serve(self) -> None:
+        """
+        Start the live server.
+        """
+        from sphinx_autobuild.__main__ import main
+
+        self.init()
+        main([str(self.doc_root), str(self.root / "dist" / "docs")])
+
+    def test(self) -> None:
+        """
+        Execute all doctests.
+        """
+
+    #
+    # Write parts of the documentation
+    #
+    def write_rst_files(self) -> None:
+        """
+        Write the index, API docs and process the User guide.
+        """
+        self.doc_root.mkdir(parents=True, exist_ok=True)
+        roots = list(self.pyproject.find_root_modules())
+        public_modules = [root.load_module() for root in roots]
+
+        for root in roots:
+            for sub_module in root.iter_submodules(skip_private=True):
+                mod = sub_module.load_module()
+                docstring = mod.docstring
+                if docstring is None:
+                    continue
+
+                if mod.exports is None:
+                    msg = "Module %s has no __all__ attribute" % sub_module.name
+                    log.warning(msg)
+                elif not mod.exports:
+                    msg = "Module %s do not export any symbols" % sub_module.name
+                    log.warning(msg)
+
+                public_modules.append(mod)
+
+        index = Index.load(self.pyproject.name, self.doc_root, public_modules)
+        index_path = self.doc_root / "index.rst"
+        index_path.write_text(index.render())
+
+        # Clean the docs/api directory
+        api_dir = self.doc_root / "api"
+        if api_dir.exists():
+            shutil.rmtree(api_dir)
+        api_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create the API documentation for each public module and the index.rst file.
+        for module in public_modules:
+            module_path = self.doc_root / "api" / f"{module.name}.rst"
+            module_path.write_text(module.render())
+        (self.doc_root / "api" / "_index.rst").write_text(
+            render_modules_index(public_modules)
+        )
+
+    def write_readme_md(self) -> None:
+        """
+        Write the README.md file for the documentation.
+        """
+        readme_path = self.root / "README.md"
+        if not readme_path.exists():
+            src = f"This is the documentation for {self.pyproject.name}. Please include a README.md file in the documentation root directory."
+            readme_path.write_text(src)
+            return
+
+        src = readme_path.read_text()
+        parts = re.split(r"<!--\s*doc0-start\s*-->", src, maxsplit=1)
+        if len(parts) == 1:
+            src = remove_md_title(src)
+        else:
+            src = parts[1]
+
+        (self.doc_root / "_readme.md").write_text(src)
+
+
+@dataclass
+class Index:
+    """
+    Content of the index.rst file.
+    """
+
+    name: str
+
+    # It uses the framework described at https://diataxis.fr
+    tutorials: Path | None = None
+    how_to_guides: Path | None = None
+    explanations: Path | None = None
+
+    # Reference is concepts + api documentation
+    concepts: Path | None = None
+    api_modules: list[str] = field(default_factory=list)
+
+    @staticmethod
+    def load(name: str, root: Path, modules: Iterable[Module]):
+        """
+        Load the index.rst configuration from the given root path and modules.
+
+        It will search the root path for the tutorials, how-to guides and
+        explanations directories in order to fill-in the appropriate fields.
+        """
+
+        module_names = [mod.name for mod in modules]
+
+        def select(name: str, plural: str | None = None) -> Path | None:
+            """
+            Select the first existing path for the given name.
+            """
+            plural = plural or name + "s"
+            return first_existing(
+                [
+                    root / plural,
+                    root / f"{name}.rst",
+                    root / f"{name}.md",
+                ]
+            )
+
+        tutorials = select("tutorial")
+        how_to_guides = select("how-to-guide")
+        explanations = select("explanation")
+        concepts = select("concept")
+
+        return Index(
+            name=name,
+            tutorials=tutorials,
+            how_to_guides=how_to_guides,
+            explanations=explanations,
+            concepts=concepts,
+            api_modules=module_names,
+        )
+
+    def render(self) -> str:
+        """
+        Render the index.rst file.
+        """
+        return "\n".join(self._iter_lines())
+
+    def _iter_lines(self) -> Iterator[str]:
+        yield f"Welcome to the {self.name} documentation!"
+        yield "=" * (len(self.name) + 30)
+        yield from [
+            ".. mdinclude:: _readme.md",
+            "",
+            "",
+            "Table of contents",
+            "-----------------",
+            "",
+            ".. toctree::",
+            "   :maxdepth: 3",
+            "",
+        ]
+
+        if self.tutorials:
+            yield f"   {self.tutorials.stem}"
+        if self.how_to_guides:
+            yield f"   {self.how_to_guides.stem}"
+        if self.explanations:
+            yield f"   {self.explanations.stem}"
+        if self.concepts:
+            yield f"   {self.concepts.stem}"
+        if self.api_modules:
+            yield "   api/_index"
+
+
+@dataclass
+class Conf:
+    """
+    Information to build the conf.py file.
+    """
+
+    project: str | None = None
+    author: str | None = None
+    email: str | None = None
+    year: int | None = None
+    extensions: list[str] = field(default_factory=DEFAULT_EXTENSIONS.copy)
+    theme: str = "default"
+    extra_options: dict[str, Any] = field(default_factory=dict)
+
+    @staticmethod
+    def from_pyproject(
+        pyproject: PyProject,
+        /,
+        *,
+        theme: str,
+        author: str | None = None,
+        email: str | None = None,
+        year: int | None = None,
+        extensions: Iterable[str] = DEFAULT_EXTENSIONS,
+        root: Path | None = None,
+    ) -> Conf:
+        """
+        Create Conf object from a PyProject object.
+        """
+        project = pyproject.name
+        extensions = list(extensions or [])
+        root = root or pyproject.root
+
+        # Extract author information from the pyproject.toml file
+        try:
+            author_data = pyproject.authors[0]
+            author = author or author_data["name"]
+            if not email:
+                email = author_data.get("email")
+        except (TypeError, IndexError):  # empty authors list or invalid data
+            pass
+
+        # Read the year from the Copyright notice in the LICENSE file.
+        if (licence_file := Path(root / "LICENSE")).exists():
+            copyright = find_copyright(licence_file.read_text())
+            if year is None:
+                try:
+                    year = int(copyright["year"])
+                except ValueError:
+                    pass
+            if author is None:
+                author = copyright["author"]
+
+        return Conf(
+            project=project,
+            author=author,
+            email=email,
+            year=year,
+            extensions=extensions,
+            theme=theme,
+        )
+
+    def render(self) -> str:
+        return "\n".join(self._iter_lines())
+
+    def _iter_lines(self) -> Iterator[str]:
+        theme = SPHINX_THEME_ALIASES.get(self.theme, self.theme)
+        copyright = f"{self.year}, " if self.year else ""
+        copyright += self.author or "unknown author"
+        author = self.author or "unknown author"
+        if self.email:
+            author += f" <{self.email}>"
+
+        yield f"project = {self.project or 'unnamed project'!r}"
+        yield f"copyright = {copyright!r}"
+        yield f"author = {author!r}"
+        yield f"extensions = {self.extensions!r}"
+        yield "templates_path = ['_templates']"
+        yield f"html_theme = {theme!r}"
+        yield "html_static_path = ['_static']"
+        yield "exclude_patterns = ['_readme.md', 'requirements.txt']"
+        for key, value in sorted(self.extra_options.items()):
+            yield f"{key} = {value!r}"
+
+
+class Copyright(TypedDict):
+    year: int
+    author: str | None
+
+
+def find_copyright(src: str) -> Copyright:
+    """
+    Find the copyright notice in the given source code.
+    """
+    match = COPYRIGHT_RE.search(src)
+    if not match:
+        raise ValueError("Copyright notice not found")
+    return {
+        "year": int(match.group("year")),
+        "author": match.group("author"),
+    }
+
+
+def render_modules_index(modules: Iterable[Module]) -> str:
+    """
+    Render the index.rst file for the API documentation.
+    """
+    lines = [
+        "Modules",
+        "=======",
+        "",
+        ".. toctree::",
+        "   :maxdepth: 2",
+        "   :caption: Contents:",
+        "",
+    ]
+    for module in modules:
+        lines.append(f"   {module.name}")
+    return "\n".join(lines)
+
+
+def remove_md_title(src: str) -> str:
+    """
+    Remove the title from the given markdown source code.
+    """
+    lines = src.splitlines()
+    if not lines:
+        return src
+
+    # Remove the first line if it is a title
+    if lines[0].startswith("#"):
+        lines.pop(0)
+        # Remove the second line if it is a title underline
+        if lines and re.match(r"^=+$", lines[0]):
+            lines.pop(0)
+
+    return "\n".join(lines).lstrip("\n")

doc0/cli.py

@@ -0,0 +1,101 @@
+"""
+CLI commands for the doc0 package.
+"""
+
+import builtins
+import sys
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from .base import Doc0
+from .util import maybe_map, validate_theme
+
+__all__ = [
+    "main",
+    #: Standalone commands
+    "test",
+    "build",
+    "serve",
+]
+
+app = typer.Typer(
+    name="doc0",
+    help="Generate documentation with zero configuration.",
+    no_args_is_help=True,
+)
+
+
+@app.command()
+def test() -> None:
+    """
+    Run all doctests for the project.
+    """
+    doc = Doc0.load(Path.cwd())
+    doc.test()
+
+
+@app.command()
+def build(
+    theme: Annotated[
+        str | None,
+        typer.Option(
+            ...,
+            "--theme",
+            help="Select the Sphinx theme",
+            callback=maybe_map(validate_theme),
+        ),
+    ] = None,
+) -> None:
+    """
+    Build the documentation for the current project.
+    """
+    doc = Doc0.load(Path.cwd(), theme=theme)
+    doc.build()
+
+
+@app.command()
+def serve(
+    theme: Annotated[
+        str | None,
+        typer.Option(
+            ...,
+            "--theme",
+            help="Select the Sphinx theme",
+            callback=maybe_map(validate_theme),
+        ),
+    ] = None,
+) -> None:
+    """
+    Serve the documentation in the live server.
+    """
+    doc = Doc0.load(Path.cwd(), theme=theme)
+    doc.serve()
+
+
+def _debug(*args: Any, **kwargs: Any) -> None:  # pragma: no cover
+    import rich
+    from rich.panel import Panel
+
+    if not args and not kwargs:
+        rich.print(sys._getframe(1).f_locals)
+        return
+
+    if args:
+        rich.print(*args)
+
+    if kwargs:
+        for k, v in kwargs.items():
+            rich.print(Panel(str(v), title=k, border_style="b"))
+
+
+def main() -> None:
+    """
+    Start the main CLI application for the doc0 package.
+    """
+    app()
+
+
+# Debug hack for efficienet print-based debugging ;)
+builtins.dbg = _debug  # type: ignore

doc0/exports.py

@@ -0,0 +1,243 @@
+# Static parsing of ``__all__`` list/tuple literals.
+#
+# Recovers declaration order and ``#:``-comment section headers from a
+# module's source, when ``__all__`` is a plain, statically analyzable
+# list/tuple of string literals. Anything else (computed values, string
+# concatenation, conditional assignment, mismatches with the module's actual
+# runtime ``__all__``, ...) is reported as "not statically determinable" so
+# callers can fall back to a simpler, unordered listing.
+#
+# Section syntax::
+#
+#     __all__ = [
+#         "Foo",
+#         "Bar",
+#         #: Utility functions
+#         "make_foo",
+#         #: Advanced
+#         #:
+#         #: These require care -- see the guide before using them.
+#         #: They are not stable across releases.
+#         "make_bar",
+#     ]
+#
+# A section is opened by a standalone comment line (nothing but whitespace
+# before the ``#``) whose text starts with ``#:``. That line's text (after
+# the marker) is the section title. Every standalone comment line
+# immediately following it -- with no blank source line or entry in
+# between -- is that section's body, rendered verbatim as paragraph text; a
+# blank comment line (``#:`` or ``#`` with nothing else) is a paragraph
+# break, and continuation lines don't need the ``#:`` marker themselves
+# (plain ``#`` works once a section has been opened). Entries before the
+# first section-opening comment form a leading, unlabeled section.
+#
+# A standalone comment block whose *first* line is not a ``#:`` line is
+# just incidental commentary: it's ignored, and does not start a section --
+# even if a `#:` line appears later in that same contiguous block. Only a
+# `#:` line reached with no other comment line directly above it opens a
+# section.
+
+from __future__ import annotations
+
+import ast
+import io
+import tokenize
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import ModuleType
+
+__all__ = ["Section", "parse_export_sections"]
+
+_SECTION_MARKER = "#:"
+
+
+@dataclass
+class Section:
+    """
+    A named (or unlabeled) group of exported symbol names, in declaration
+    order.
+    """
+
+    #: The section title, taken from a ``#:``-opened comment block
+    #: preceding this group's first entry. None for the leading,
+    #: unlabeled group of entries that appear before any such block (or
+    #: for the whole list, if it has no section comments at all).
+    title: str | None
+
+    #: Body paragraph lines for this section, verbatim from the comment
+    #: block (empty strings mark paragraph breaks). Always empty when
+    #: title is None.
+    body: list[str] = field(default_factory=list)
+
+    #: Exported symbol names belonging to this section, in declaration order.
+    names: list[str] = field(default_factory=list)
+
+
+def parse_export_sections(
+    source_path: Path, module: ModuleType
+) -> list[Section] | None:
+    """
+    Parse ``__all__`` in the given source file into ordered, ``#:``-delimited
+    sections, if -- and only if -- it can be statically and reliably
+    determined.
+
+    Returns None when ``__all__`` is missing, is not a single top-level
+    plain list/tuple of string literals, or its statically-parsed names
+    don't exactly match the module's actual runtime ``__all__`` (e.g.
+    because it's built dynamically, conditionally, or mutated after
+    definition) -- callers should fall back to whatever default listing
+    they'd otherwise use in that case.
+    """
+    runtime_all = getattr(module, "__all__", None)
+    if runtime_all is None:
+        return None
+
+    try:
+        source = source_path.read_text()
+    except OSError:
+        return None
+
+    node = _find_all_literal(source)
+    if node is None:
+        return None
+
+    names = _extract_string_literal_names(node)
+    if names is None or names != list(runtime_all):
+        return None
+
+    return _split_into_sections(source, node, names)
+
+
+def _find_all_literal(source: str) -> ast.List | ast.Tuple | None:
+    """
+    Find a single, top-level, unconditional ``__all__ = [...]`` (or
+    ``(...)``) assignment and return its list/tuple node, or None if
+    there isn't exactly one such simple assignment.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+
+    found: ast.List | ast.Tuple | None = None
+    for stmt in tree.body:
+        if "__all__" not in _assignment_targets(stmt):
+            continue
+        value = stmt.value  # type: ignore[union-attr]
+        if not isinstance(value, (ast.List, ast.Tuple)) or found is not None:
+            # Not a plain literal, or a second __all__ assignment: too
+            # ambiguous to trust statically.
+            return None
+        found = value
+
+    return found
+
+
+def _assignment_targets(stmt: ast.stmt) -> list[str]:
+    if isinstance(stmt, ast.Assign):
+        return [target.id for target in stmt.targets if isinstance(target, ast.Name)]
+    if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+        return [stmt.target.id]
+    return []
+
+
+def _extract_string_literal_names(node: ast.List | ast.Tuple) -> list[str] | None:
+    names = []
+    for element in node.elts:
+        if not (isinstance(element, ast.Constant) and isinstance(element.value, str)):
+            return None
+        names.append(element.value)
+    return names
+
+
+def _split_into_sections(
+    source: str, node: ast.List | ast.Tuple, names: list[str]
+) -> list[Section]:
+    """
+    For each entry, look at the contiguous run of standalone comment
+    lines immediately preceding it (if any) to decide whether it opens a
+    new section, then group entries accordingly.
+    """
+    comment_lines = _standalone_comment_lines(source, node)
+
+    sections: list[Section] = []
+    current = Section(title=None)
+    sections.append(current)
+
+    previous_end_line = node.lineno  # exclusive lower bound for the next backward scan
+
+    for element, name in zip(node.elts, names):
+        run = _preceding_comment_run(comment_lines, previous_end_line, element.lineno)
+        if run and run[0].startswith(_SECTION_MARKER):
+            title = run[0][len(_SECTION_MARKER) :].strip()
+            body = [_strip_comment_marker(line) for line in run[1:]]
+            body = _strip_blank_edges(body)
+            current = Section(title=title, body=body)
+            sections.append(current)
+        current.names.append(name)
+        previous_end_line = element.lineno + 1
+
+    return [section for section in sections if section.names]
+
+
+def _strip_blank_edges(body: list[str]) -> list[str]:
+    """
+    Drop leading/trailing blank paragraph-break lines (they're just the
+    blank-line-after-title artifact, not meaningful spacing); internal
+    blank lines between paragraphs are kept.
+    """
+    start = 0
+    end = len(body)
+    while start < end and not body[start]:
+        start += 1
+    while end > start and not body[end - 1]:
+        end -= 1
+    return body[start:end]
+
+
+def _strip_comment_marker(text: str) -> str:
+    if text.startswith(_SECTION_MARKER):
+        return text[len(_SECTION_MARKER) :].strip()
+    return text[1:].strip()  # plain "#" comment
+
+
+def _preceding_comment_run(
+    comment_lines: dict[int, str], lower_bound: int, before_line: int
+) -> list[str]:
+    """
+    Collect the contiguous run of standalone comment lines ending right
+    before `before_line`, without crossing `lower_bound` (the line right
+    after the previous entry, or the list's opening line).
+    """
+    run: list[str] = []
+    line_no = before_line - 1
+    while line_no >= lower_bound and line_no in comment_lines:
+        run.append(comment_lines[line_no])
+        line_no -= 1
+    run.reverse()
+    return run
+
+
+def _standalone_comment_lines(
+    source: str, node: ast.List | ast.Tuple
+) -> dict[int, str]:
+    """
+    Return {line_number: raw_comment_text} for every comment that is the
+    only non-whitespace content on its line, within the span of `node`.
+    """
+    end_line = node.end_lineno or node.lineno
+    lines: dict[int, str] = {}
+
+    for tok in tokenize.generate_tokens(io.StringIO(source).readline):
+        if tok.type != tokenize.COMMENT:
+            continue
+        line_no, col = tok.start
+        if not (node.lineno <= line_no <= end_line):
+            continue
+        if tok.line[:col].strip():
+            # Something other than whitespace precedes the comment on its
+            # line: a trailing same-line comment, not standalone.
+            continue
+        lines[line_no] = tok.string
+
+    return lines

doc0/module.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import inspect
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Iterator
+
+from .exports import Section, parse_export_sections
+
+
+@dataclass(frozen=True)
+class ModuleSpec:
+    #: The Python module name
+    name: str
+
+    #: The path to the module source file. Packages point to a folder, modules to a file.
+    path: Path
+
+    @property
+    def is_package(self) -> bool:
+        """
+        Return True if the module is a package.
+        """
+        return self.path.is_dir()
+
+    @property
+    def source_path(self) -> Path:
+        """
+        Return the path to the source file for the module.
+        """
+        if self.is_package:
+            return self.path / "__init__.py"
+        return self.path
+
+    def __post_init__(self) -> None:
+        if not self.path.exists():
+            raise ValueError(f"Module path {self.path} does not exist.")
+
+        if self.path.name == "__init__.py":
+            super().__setattr__("path", self.path.parent)
+
+        elif not self.path.is_dir() and self.path.suffix != ".py":
+            raise ValueError(f"Module path {self.path} is not a Python file.")
+
+    def load_module(self) -> Module:
+        """
+        Load the module from the spec.
+
+        This executes the module code, if not already loaded.
+        """
+        import importlib.util
+
+        if self.name in sys.modules:
+            module = sys.modules[self.name]
+        else:
+            if self.is_package:
+                submodule_search_locations = [str(self.path)]
+            else:
+                submodule_search_locations = None
+            spec = importlib.util.spec_from_file_location(
+                name=self.name,
+                location=self.source_path,
+                submodule_search_locations=submodule_search_locations,
+            )
+            if spec is None:
+                raise ImportError(f"Cannot load module {self.name} from {self.path}")
+            module = importlib.util.module_from_spec(spec)
+            if spec.loader is None:
+                raise ImportError(f"Cannot load module {self.name} from {self.path}")
+            spec.loader.exec_module(module)
+
+        return Module(source_path=self.source_path, name=self.name, module=module)
+
+    def iter_submodules(self, skip_private: bool = False) -> Iterator[ModuleSpec]:
+        """
+        Iterate over all sub-modules in the project.
+        """
+        if self.is_package:
+            for path in self.path.iterdir():
+                if skip_private and path.name.startswith("_"):
+                    continue
+
+                if path.is_dir():
+                    spec = ModuleSpec(name=f"{self.name}.{path.name}", path=path)
+                    if (path / "__init__.py").exists():
+                        yield spec
+                    yield from spec.iter_submodules(skip_private=skip_private)
+
+                elif path.suffix == ".py":
+                    yield ModuleSpec(name=f"{self.name}.{path.stem}", path=path)
+
+
+@dataclass
+class Module:
+    """
+    A Python module with its source and objects.
+    """
+
+    #: Path to the source file
+    source_path: Path
+
+    #: Python name for the module.
+    name: str
+
+    #: Loaded python module
+    module: ModuleType
+
+    @property
+    def docstring(self) -> str | None:
+        """
+        Return the module docstring.
+        """
+        return self.module.__doc__
+
+    @property
+    def exports(self) -> list[str] | None:
+        """
+        Return the list of exported symbols from the module.
+        """
+        exports = getattr(self.module, "__all__", None)
+        if exports is None:
+            return None
+        return list(exports)
+
+    def render(self) -> str:
+        """
+        Render the module documentation as reStructuredText.
+
+        If ``__all__`` can be statically parsed into ordered, ``#:``-delimited
+        sections (see ``doc0.exports``), members are listed explicitly, in
+        declaration order, grouped under their sections. Otherwise, falls
+        back to a single ``automodule`` block listing all members in
+        whatever order Sphinx's autodoc picks.
+        """
+        return "\n".join(self._iter_lines())
+
+    def _iter_lines(self) -> Iterator[str]:
+        yield self.name
+        yield "=" * len(self.name)
+        yield ""
+
+        sections = parse_export_sections(self.source_path, self.module)
+        if sections is None:
+            yield f".. automodule:: {self.name}"
+            yield "   :members:"
+            return
+
+        yield f".. automodule:: {self.name}"
+        yield ""
+
+        for section in sections:
+            yield from self._iter_section_lines(section)
+
+    def _iter_section_lines(self, section: Section) -> Iterator[str]:
+        if section.title:
+            yield section.title
+            yield "-" * len(section.title)
+            yield ""
+
+        for line in section.body:
+            yield line
+        if section.body:
+            yield ""
+
+        for name in section.names:
+            yield from self._iter_member_lines(name)
+            yield ""
+
+    def _iter_member_lines(self, name: str) -> Iterator[str]:
+        qualname = f"{self.name}.{name}"
+        obj = getattr(self.module, name, None)
+
+        if inspect.isclass(obj):
+            yield f".. autoclass:: {qualname}"
+            yield "   :members:"
+        elif inspect.isroutine(obj):
+            yield f".. autofunction:: {qualname}"
+        else:
+            yield f".. autodata:: {qualname}"

doc0/pyproject.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from logging import getLogger
+from pathlib import Path
+from typing import Any, Iterable, NotRequired, TypedDict, overload
+from warnings import warn
+
+from .module import ModuleSpec
+
+log = getLogger(__name__)
+type TomlValue = str | int | float | bool | None | list[Any] | dict[str, Any]
+
+
+@dataclass
+class PyProject:
+    """
+    A Python project with its source and documentation.
+    """
+
+    #: Path to the root of the project
+    root: Path
+
+    #: Raw data from the pyproject.toml file
+    data: dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """
+        Load the pyproject.toml file if it exists.
+        """
+        pyproject_path = self.root / "pyproject.toml"
+        if pyproject_path.exists():
+            with pyproject_path.open("rb") as f:
+                self.data = tomllib.load(f)
+        else:
+            warn("pyproject.toml not found")
+
+    @property
+    def project(self) -> dict[str, TomlValue]:
+        return self.data.get("project", {})
+
+    @property
+    def name(self) -> str:
+        return self.get("project.name", type=str)
+
+    @property
+    def version(self) -> str:
+        return self.get("project.version", type=str)
+
+    @property
+    def description(self) -> str:
+        return self.get("project.description", type=str)
+
+    @property
+    def authors(self) -> list[Author]:
+        data = self.get("project.authors", type=list)
+        return [Author(**item) for item in data]
+
+    def __getitem__(self, key: str) -> TomlValue:
+        data = self.data
+        for part in key.split("."):
+            try:
+                data = data[part]
+            except KeyError:
+                raise KeyError(key)
+        return data
+
+    @overload
+    def get[T](self, key: str, /, *, default: T | None = None, type: type[T]) -> T: ...
+
+    @overload
+    def get(self, key: str, /, default: TomlValue = None) -> TomlValue: ...
+
+    def get(self, key: str, /, default: Any = None, *, type: Any = None) -> Any:
+        """
+        Get configuration key and possibly assert it has the given type.
+
+        Args:
+            key: The key to get, using dot notation for nested keys.
+            default: The default value to return if the key is not found.
+            type: The type to assert the value has. If None, no assertion is made.
+        """
+        try:
+            value = self[key]
+        except KeyError:
+            value = default
+        if type is not None and value is not None and not isinstance(value, type):
+            msg = f"Expected {key} to be of type {type.__name__}, got {value.__class__.__name__}"
+            raise TypeError(msg)
+        return value
+
+    def find_root_modules(self) -> Iterable[ModuleSpec]:
+        """
+        Find all root modules in the project.
+
+        Returns:
+            An iterable of root module specifications.
+        """
+        # We try various heuristics to find the root modules of the project.
+        # The first is to look for explicit configuration in the pyproject.toml
+        # file.
+        if self._is_uv_build_system():
+            log.info("uv build system detected")
+            yield from self._find_uv_root_modules()
+        elif self._is_src_layout():
+            yield from self._find_src_root_modules()
+        elif self._is_toplevel_package_layout():
+            log.info("toplevel package layout detected")
+            yield from self._find_toplevel_package_root_modules()
+        else:
+            raise RuntimeError("Could not determine the layout of the project")
+
+    def _is_uv_build_system(self) -> bool:
+        build_system: dict[str, str] = self.data.get("build-system", {})
+        return build_system.get("build-backend") == "uv_build"
+
+    def _is_src_layout(self) -> bool:
+        # Check if there is a src directory with a package inside it.
+        src_dir = self.root / "src"
+        if not src_dir.is_dir():
+            return False
+        for item in src_dir.iterdir():
+            if item.is_dir() and (item / "__init__.py").exists():
+                return True
+        return False
+
+    def _is_toplevel_package_layout(self) -> bool:
+        package_dir = self.root / self.name
+        return package_dir.is_dir() and (package_dir / "__init__.py").exists()
+
+    def _find_uv_root_modules(self) -> Iterable[ModuleSpec]:
+        uv_conf = self.get("tool.uv.build-backend", type=dict)
+        root = self.root / uv_conf.get("module-root", "")
+        name = uv_conf.get("module-name")
+        if name is None:
+            return
+        if isinstance(name, str) and "," in name:
+            name = [part.strip() for part in name.split(",")]
+
+        if isinstance(name, list):
+            yield from (ModuleSpec(name=part, path=root / part) for part in name)
+        elif isinstance(name, str):
+            yield ModuleSpec(name=name, path=root / name)
+        else:
+            msg = f"Invalid option: tool.uv.build-backend.module-name={name!r}"
+            raise ValueError(msg)
+
+    def _find_src_root_modules(self) -> Iterable[ModuleSpec]:
+        src_dir = self.root / "src"
+        for item in src_dir.iterdir():
+            if item.is_dir() and (item / "__init__.py").exists():
+                yield ModuleSpec(name=item.name, path=item)
+            elif item.suffix == ".py":
+                yield ModuleSpec(name=item.stem, path=item)
+
+    def _find_toplevel_package_root_modules(self) -> Iterable[ModuleSpec]:
+        package_dir = self.root / self.name
+        yield ModuleSpec(name=self.name, path=package_dir)
+
+
+#
+# Auxiliary types
+#
+class Author(TypedDict):
+    name: str
+    email: NotRequired[str]

doc0/util.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+from typing import Any, Callable, Iterable, overload
+
+
+def validate_theme(theme: str) -> str:
+    """
+    Validate the provided theme for Sphinx documentation.
+
+    Args:
+        theme (str): The name of the Sphinx theme to validate.
+
+    Raises
+        ValueError: If the provided theme is not a valid Sphinx theme.
+
+    Examples:
+        >>> validate_theme("alabaster")
+        'alabaster'
+        >>> validate_theme("bad theme")
+        Traceback (most recent call last):
+            ...
+        ValueError: 'bad theme' is not a valid Sphinx theme.
+    """
+    parts = theme.split(".")
+    for part in parts:
+        if not part.isidentifier():
+            raise ValueError(f"'{theme}' is not a valid Sphinx theme.")
+
+    return theme
+
+
+@overload
+def maybe_map[T, R](fn: Callable[[T], R], value: T | None, /) -> R | None: ...
+
+
+@overload
+def maybe_map[T, R](fn: Callable[[T], R], /) -> Callable[[T | None], R | None]: ...
+
+
+def maybe_map[T, R](fn: Callable[[T], R], /, *args: Any) -> Any:
+    """
+    Apply a function to a value if it is not None, otherwise return None.
+
+    Curried.
+    """
+    if args:
+        value = args[0]
+        if value is not None:
+            return fn(value)
+    else:
+        return lambda value: maybe_map(fn, value)
+    return None
+
+
+def first_existing(paths: Iterable[Path]) -> Path | None:
+    """
+    Return the first existing path from the provided iterable of paths.
+    """
+    for path in paths:
+        if path.exists():
+            return path
+    return None

doc_zero-0.1.1.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: doc-zero
+Version: 0.1.1
+Summary: Zero-configuration documentation generator for Python.
+Author: Fábio Macêdo Mendes
+Author-email: Fábio Macêdo Mendes <fabiomacedomendes@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Dist: myst-parser>=5.1.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: sphinx>=9.1.0
+Requires-Dist: sphinx-autobuild>=2025.8.25
+Requires-Dist: sphinx-mdinclude>=0.6.2
+Requires-Dist: sphinx-rtd-theme>=3.1.0
+Requires-Dist: typer>=0.27.0
+Maintainer: Fábio Macêdo Mendes
+Maintainer-email: Fábio Macêdo Mendes <fabiomacedomendes@gmail.com>
+Requires-Python: >=3.13
+Project-URL: Homepage, http://github.com/fabiommendes/zero-doc
+Project-URL: Repository, http://github.com/fabiommendes/zero-doc
+Project-URL: Documentation, https://zero-doc.readthedocs.io/
+Description-Content-Type: text/markdown
+
+# doc-zero
+
+`doc-zero` streamlines the process of writing documentation for your project. It is
+an opinionated and explicitly non-configurable tool that extracts information
+from your Python codebase and generates nice documentation with minimal effort.
+
+The main influence is the `elm` language tooling: no config, nice defaults and
+it creates a very decent documentation out of the box. Rust has a similar
+experience with RustDoc. In comparison, both Sphinx and MkDocs are very powerful
+but somewhat clunky to use and configure.
+
+## How does it work?
+
+`doc0` introspect your codebase and creates a Sphinx project under the hood. In
+practice, if you have a relatively modern Python project (i.e., it assumes the
+existence of pyproject.toml) just type
+
+```bash
+$ doc0 build
+```
+
+in the project root and it will create and build the documentation under
+`<project-root>/docs`. In `doc0`, all your documentation resides either in the
+README.md file in your repository or inside the source code.
+
+You can also type
+
+```bash
+$ doc0 serve
+```
+
+and
+
+```bash
+doc0 test
+```
+
+to run either the live server or to test the doctests inside the documentation.
+
+
+## Adding the documentation to your project
+
+Doc0 assumes your project is already documented using docstrings and that 
+you have a README.md file in the project root. It will use those assets to
+generate the documentation and the necessary configurations to make it buildable
+with Sphinx and ready to be hosted to readthedocs.io. 
+
+The first step is to install `doc0` as a development dependency in your project. 
+You can do this by running
+
+```bash
+$ pip install doc0
+```
+
+or the equivalent command for the package manager of choice.
+
+
+Then, the following command generates the documentation:
+
+```bash
+$ doc0 build
+```
+
+`doc0` always creates a module documentation for your toplevel module. It will
+also scan all sub-modules and generate a documentation page if they satisfy the
+following conditions:
+
+* The module is not private (i.e., it does not start with an underscore).
+* The module has a docstring.
+* The module defines a `__all__` variable that lists its public API.
+
+`doc0` only includes the public API in the generated documentation. 
+

doc_zero-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+doc0/__init__.py,sha256=V8M8QzlEMiXC2LCbJXP3bIZawLl-6j3Y-O4g-rlrvGU,200
+doc0/__main__.py,sha256=Qd-f8z2Q2vpiEP2x6PBFsJrpACWDVxFKQk820MhFmHo,59
+doc0/base.py,sha256=lyk28CqvYRGJYZy5IW0ZmgD6439cwZhvpHgNipH9Ny0,12917
+doc0/cli.py,sha256=XjoF-hyLmA9AmWFsu1nmFWqi0_eDHGEYIpS9_be6f3g,1909
+doc0/exports.py,sha256=jYO9M9Yr379lJ_qbIKHMs9c1J4WWclCUPvAm8uYWUD0,8459
+doc0/module.py,sha256=xpTp01MNv4yl8rFG-2-f7c7_vmv3vo7IjDSAjTeXvg8,5520
+doc0/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+doc0/pyproject.py,sha256=bjFhi6k0nfm0usDDmJ_WW9HTNkMGvqpkZt_6Q3jjNzY,5667
+doc0/util.py,sha256=2d8Kqf0dHKa7A-Z_yqnvOCu4G6hGxWsMvyR1rjOLfmc,1530
+doc_zero-0.1.1.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
+doc_zero-0.1.1.dist-info/entry_points.txt,sha256=2xR_j_sMlnOjy6dEWy0t_pfWU8Hp1UhNEDlWjhy7CEk,65
+doc_zero-0.1.1.dist-info/METADATA,sha256=bO7c0mYXUL59x5qCesB6qCJse2dlD7TmsZdybeYtFtc,3354
+doc_zero-0.1.1.dist-info/RECORD,,

doc_zero-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.5
+Root-Is-Purelib: true
+Tag: py3-none-any

doc_zero-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+doc-zero = doc0.cli:main
+doc0 = doc0.cli:main
+