Documentation Generation
Relevant source files
The following files were used as context for generating this wiki page:
The documentation generation system in the MBBank project is designed to automatically produce comprehensive technical references for the library's modules, including its synchronous and asynchronous APIs. It leverages automated tools to extract docstrings, format them according to Google standards, and include source code for developer transparency.
The system is primarily driven by pdoc, a Python documentation generator, and is integrated into the development workflow to ensure that the documentation remains in sync with the codebase. The generation process also handles supplemental assets, such as preloaded templates, to customize the output's appearance and functionality.
Sources: docs_gen.py:1-49, CONTRIBUTING.md:25-30, mbbank/init.py:1-118
System Architecture and Workflow
The documentation system follows a structured pipeline where specific modules are targeted for rendering. The process involves configuring the rendering engine, processing the target modules, and moving static templates into the final output directory.
Core Documentation Pipeline
The generation logic is encapsulated in a dedicated script that defines the scope of documentation and the output location.
The diagram shows the logical flow from script execution to the final distribution of HTML files and assets.
Sources: docs_gen.py:28-44
Target Modules for Documentation
The system specifically targets several sub-packages within the mbbank library to ensure all functional areas are covered:
| Module Path | Description |
|---|---|
mbbank | Top-level package and convenience exports |
mbbank.capcha_ocr | Image processing and OCR logic |
mbbank.sync | Synchronous API implementation |
mbbank.aio | Asynchronous API implementation |
mbbank.modals | Pydantic response models and data structures |
mbbank.errors | Custom exception classes |
Sources: docs_gen.py:21-28, mbbank/init.py:8-13
Technical Implementation
Toolchain Integration
Documentation generation is part of the broader development environment. The project uses uv or pip to manage dependencies required for building the docs.
- Primary Tool:
pdoc(version 16.0.0) is used for rendering. - Code Standards: Documentation comments must follow the
googledocstring format. - Exclusions: The system is configured to
include_undocumented=False, meaning only explicitly documented members appear in the output.
Sources: pyproject.toml:34-38, docs_gen.py:38-40, CONTRIBUTING.md:25-30
Asset Management and Templating
Beyond standard code rendering, the system includes a copy_preload mechanism. This utility traverses a template directory and replicates its structure in the output directory, allowing for custom CSS, JavaScript, or images to be bundled with the generated HTML.
def copy_preload(path_out: Path) -> None:
template_dir = Path("docs/templates/preload")
path_out.mkdir(parents=True, exist_ok=True)
for item in template_dir.rglob("*"):
if item.is_file():
rel_path = item.relative_to(template_dir)
dest_path = path_out / rel_path
dest_path.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(item, dest_path)
Sources: docs_gen.py:8-20
Execution and Configuration
Command-Line Interface
The generation script supports an optional flag for CI/CD environments, specifically ReadTheDocs (RTFD). When the --rtfd flag is detected, the script redirects output to the location expected by the RTFD build environment.
- Standard Build:
python docs_gen.py - RTFD Build:
python docs_gen.py --rtfd
Sources: docs_gen.py:47-49, CONTRIBUTING.md:29
Linting and Formatting
The project enforces strict linting via ruff, which also affects documentation quality. Specific rules are configured to accommodate the MBBank API's nature, such as allowing ambiguous Unicode characters in docstrings to support Vietnamese text.
| Rule Code | Description | Rationale |
|---|---|---|
RUF002 | ambiguous-unicode-character-docstring | Ignored to allow Vietnamese text in documentation |
N815/N802 | mixed-case-variable/function-name | Ignored to match MBBank's camelCase API endpoints |
Sources: ruff.toml:1-35
Conclusion
The documentation generation system ensures that the MBBank SDK remains accessible and well-documented. By integrating pdoc with custom template preloading and specific linting rules, the project provides technically accurate, searchable, and localized documentation that mirrors the underlying API's structure.