Gen docs

DocsGenerator

Bases: BaseModel


              flowchart TD
              scripts.gen_docs.DocsGenerator[DocsGenerator]

              

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

Generate module markdown pages and rebuild the MkDocs nav.

Attributes:

Name	Type	Description
`source_path`	`Path`	Source directory or file path.
`output_path`	`Path`	Output directory path.
`exclude`	`str`	Comma-separated list of folders or files to exclude.
`mode`	`Literal['file', 'class']`	Whether to generate docs by file or class.
`execute`	`bool`	Whether to execute notebooks before converting them.
`concurrency`	`int`	Maximum number of files to process concurrently.

Examples:

Generate docs pages

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

Rebuild mkdocs nav

uv run ./scripts/gen_docs.py build_nav

Methods:

Name	Description
`gen_docs`	Generates per-module markdown pages from the source files.
`build_nav`	Rewrite the auto-generated MkDocs nav block by scanning the docs tree.

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]

The source files selected for documentation generation.

Returns:

Type	Description
`list[Path]`	list[Path]: Source files under `source_path`, excluding configured entries and
`list[Path]`	default skipped paths when `source_path` is a directory. Returns the
`list[Path]`	single source file when `source_path` is a file, or an empty list
`list[Path]`	when it is neither a valid file nor directory.

gen_docs

gen_docs() -> None

Generates per-module markdown pages from the source files.

Source code in scripts/gen_docs.py

async def gen_docs(self) -> None:
    """Generates per-module markdown pages from the source files."""
    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

        results = await self._process_batch(self.source_files, progress, task)

        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 (str): Path to the MkDocs source directory (where `index.md` lives).
        config_path (str): Path to the `mkdocs.yml` to update in-place.
        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.
    """
    _rebuild_nav(docs_dir=docs_dir, config_path=config_path, sections=sections)