Gen docs

DocsGenerator

Bases: BaseModel

DocsGenerator is a class that generates documentation for Python files or classes within a specified source directory.

Attributes:

Name	Type	Description
source	str	The source directory or file path.
output	str	The 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	Generates documentation by file or class.
__call__	Asynchronously calls the gen_docs method.

Examples:

Using CLIUsing uv

python ./scripts/gen_docs.py --source ./src --output ./docs/Reference --exclude .venv gen_docs

uv run python ./scripts/gen_docs.py

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,
    )