Documentation Generation

Relevant source files

The following files were used as context for generating this wiki page:

• dev/knowledge/doc-generation.md
• tasks.py
• dev/constitution.md
• AGENTS.md
• pyproject.toml
• tests/unit/doc_generation/mdx/conftest.py

Documentation generation in the Infrahub Python SDK project automates the creation of technical references for the infrahubctl CLI and the Python SDK. The system produces MDX files from source code, ensuring that the documentation remains synchronized with the latest functional changes. This process is a non-negotiable requirement for all contributions; developers must regenerate and commit updated documentation whenever CLI commands, configuration models, or public docstrings change.

Sources: dev/knowledge/doc-generation.md:3-5, dev/constitution.md:121-125, AGENTS.md:57-58

Core Generation Workflow

The documentation generation system relies on invoke tasks to orchestrate different generators. The primary entry point is the docs-generate task, which triggers sub-tasks for the CLI, SDK API, configuration, and compatibility matrix.

The workflow ensures a clean state by deleting existing generated files before writing new ones, particularly for CLI documentation to reflect changes in command structures.
Sources: tasks.py:64-70, tasks.py:182-192, dev/knowledge/doc-generation.md:10-14

Infrahubctl CLI Documentation

CLI documentation is derived directly from the Typer application instance. The generator iterates through registered commands and groups, producing individual MDX files for each root-level command.

CLI Mapping Logic

• Root Commands: A command named foo generates infrahubctl-foo.mdx.
• Subcommand Groups: A group named bar generates infrahubctl-bar.mdx and includes all nested subcommands.
• Tools: The process utilizes typer-cli logic to extract command help text and options.

Sources: tasks.py:72-90, dev/knowledge/doc-generation.md:16-24

SDK Reference Generation

SDK documentation is split into API references and static reference pages (Configuration, Compatibility, and Templating).

API Reference (mdxify)

The system uses mdxify to generate API documentation for specific Python modules. The get_modules_to_document() function manages which packages are included or ignored.

Category	Modules/Packages
Documented Packages	graph_traversal, node
Ignored Packages	ctl, graphql, protocols_generator, pytest_plugin, schema, spec, task, template, testing, transfer
Extra Modules	infrahub_sdk.client

Sources: tasks.py:151-180

Priority and Ordering

The PAGE_PRIORITIES dictionary defines the internal structure of generated MDX files, ensuring important classes and methods appear first.

PAGE_PRIORITIES: dict[str, PagePriority] = {
    "infrahub_sdk-client.mdx": PagePriority(
        sections=["Classes"],
        classes=["InfrahubClient", "InfrahubClientSync"],
        methods={
            "InfrahubClient": ["get", "delete", "create"],
            "InfrahubClientSync": ["get", "delete", "create"],
        },
    ),
}

Sources: tasks.py:28-40

Validation and Quality Gates

The project enforces documentation accuracy through CI/CD gates and linting tools.

• Sync Validation: The docs-validate task regenerates all documentation and runs git diff. If the generated files differ from those committed in the repository, the task exits with an error.
• Linting: Multiple tools validate the documentation quality:
  • rumdl: Checks markdown structure and automatically fixes violations.
  • vale: Validates documentation style and prose against project standards.

Sources: tasks.py:257-276, tasks.py:228-241, pyproject.toml:390-406

Documentation Commands Summary

Command	Purpose
uv run invoke docs-generate	Generates all CLI and SDK MDX files.
uv run invoke docs-validate	Verifies that committed docs match the code state.
uv run invoke lint-docs	Runs rumdl and vale on documentation files.
uv run invoke docs	Builds the final documentation website using Docusaurus (npm run build).

Sources: tasks.py:63-68, tasks.py:252-255, tasks.py:279-286, AGENTS.md:29-30

Implementation Components

The generation logic is implemented using specialized classes within the docs.docs_generation package.

The use of Jinja2DocContentGenMethod allows for specialized pages like the compatibility matrix, which consumes variables defined in docs.docs_generation.compatibility.
Sources: tasks.py:121-131

Conclusion

Documentation generation is a centralized, automated process that treats documentation as code. By utilizing mdxify, typer, and Jinja2, the project maintains a comprehensive set of references that are strictly validated in CI. This architecture ensures that network automation engineers always have access to accurate, up-to-date SDK and CLI information.