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