Gen docs

DocsGenerator

Bases: BaseModel


              flowchart TD
              scripts.gen_docs.DocsGenerator[DocsGenerator]

              

              click scripts.gen_docs.DocsGenerator href "" "scripts.gen_docs.DocsGenerator"

DocsGenerator generates per-module markdown pages from a Python source tree and rebuilds the MkDocs nav block.

Attributes:

Name	Type	Description
`source`	`str`	Source directory or file path.
`output`	`str`	Output directory path.
`exclude`	`str`	Comma-separated list of folders or files to exclude.
`mode`	`Literal['file', 'class']`	Mode of documentation generation, either by file or class.

Methods:

Name	Description
`gen_docs`	Generate per-module markdown pages from a Python or notebook source tree.
`build_nav`	Rewrite the auto-generated MkDocs nav block by scanning `docs/`.

Examples:

Generate docs pagesRebuild mkdocs nav

uv run ./scripts/gen_docs.py --source ./src --output ./docs/Reference gen_docs

uv run ./scripts/gen_docs.py build_nav

source_path

source_path: Path = Field(
    ...,
    title="The Source File Path or Folder Path",
    description="This field can be a file path or folder path, if it is a folder path, it will automatically search for python and ipynb files.",
    examples=["./src"],
    alias="source",
    frozen=True,
)

output_path

output_path: Path = Field(
    ...,
    title="The Output Path",
    description="The output path for the generated documentation.",
    examples=["./docs/Reference"],
    alias="output",
    frozen=True,
)

exclude

exclude: str = Field(
    default=".venv",
    description="Exclude the folder or file, it should be separated by comma.",
    examples=[".venv,.git,.idea"],
)

mode

mode: Literal["file", "class"] = Field(
    default="class",
    title="The Document Style",
    description="Generate docs by file or class.",
    examples=["file", "class"],
)

execute

execute: bool = Field(
    default=False,
    title="Execute Notebook",
    description="Execute the notebook before generating the documentation.",
    examples=["True", "False"],
)

concurrency

concurrency: int = Field(
    default=10,
    title="Concurrency Limit",
    description="Maximum number of files to process concurrently.",
    examples=[5, 10, 20],
)

source_files

source_files: list[Path]

Computed property that returns the source path as a Path object.

Returns:

Name	Type	Description
`Path`	`list[Path]`	The source path.

gen_docs

gen_docs() -> None

Source code in scripts/gen_docs.py

async def gen_docs(self) -> None:
    with Progress() as progress:
        total_files = len(self.source_files)
        task = progress.add_task(f"[green]Generating {total_files}...", total=total_files)

        if not self.source_files:
            console.log("[yellow]No files found to process")
            return

        # Process all files concurrently with controlled concurrency
        results = await self._process_batch(self.source_files, progress, task)

        # Summarize results
        successful = len([r for r in results if r])
    console.log(
        f"[green]Documentation generation complete ({successful}/{total_files})!",
        highlight=True,
    )

build_nav

build_nav(
    docs_dir: str = "docs",
    config_path: str = "mkdocs.yml",
    sections: tuple[str, ...] = ("Reference", "Scripts"),
) -> None

Rewrite the auto-generated MkDocs nav block by scanning the docs tree.

The script walks each requested top-level section under docs_dir and emits a nested nav YAML structure so the sidebar shows every leaf module directly. It rewrites only the region delimited by the sentinel comments in config_path; everything outside the markers is preserved verbatim.

Exposed as a @staticmethod so Fire can dispatch gen_docs.py build_nav without instantiating DocsGenerator (which would require --source / --output that are irrelevant here).

Parameters:

Name	Type	Description	Default
`docs_dir`	`str`	Path to the MkDocs source directory (where `index.md` lives).	`'docs'`
`config_path`	`str`	Path to the `mkdocs.yml` to update in-place.	`'mkdocs.yml'`
`sections`	`tuple[str, ...]`	Top-level directory names under `docs_dir` to expose as expandable nav sections. Sections that do not exist on disk are silently skipped.	`('Reference', 'Scripts')`

Source code in scripts/gen_docs.py

@staticmethod
def build_nav(
    docs_dir: str = "docs",
    config_path: str = "mkdocs.yml",
    sections: tuple[str, ...] = ("Reference", "Scripts"),
) -> None:
    """Rewrite the auto-generated MkDocs nav block by scanning the docs tree.

    The script walks each requested top-level section under ``docs_dir`` and
    emits a nested nav YAML structure so the sidebar shows every leaf module
    directly. It rewrites only the region delimited by the sentinel comments
    in ``config_path``; everything outside the markers is preserved verbatim.

    Exposed as a ``@staticmethod`` so Fire can dispatch
    ``gen_docs.py build_nav`` without instantiating ``DocsGenerator`` (which
    would require ``--source`` / ``--output`` that are irrelevant here).

    Args:
        docs_dir: Path to the MkDocs source directory (where ``index.md`` lives).
        config_path: Path to the ``mkdocs.yml`` to update in-place.
        sections: Top-level directory names under ``docs_dir`` to expose as
            expandable nav sections. Sections that do not exist on disk are
            silently skipped.
    """
    _rebuild_nav(docs_dir=docs_dir, config_path=config_path, sections=sections)