#201 / IHS-194: Generate SDK API documentation

[polmichel]

Why

Problem Statement

• There is no Python SDK API Documentation today.
• The existing documentation generation system (tasks.py) was a monolithic set of functions mixing concerns (template rendering, CLI execution, file I/O), making it hard to understand and to extend with new generation methods.
• Docusaurus sidebars were statically hardcoded, requiring manual edits whenever a doc page was added or removed.

Goals

This PR:

• Introduces automatic Python SDK API documentation generation from code docstrings using mdxify
• Refactors the documentation generation pipeline into an extensible architecture
• Makes Docusaurus sidebars dynamic.

Closes IHS-194, IHS-195, IHS-196, IHS-197, IHS-198, IHS-199, IHS-200, IHS-201

What changed

• New SDK API docs from docstrings IHS-196: Added mdxify-based generation (generate-sdk-api-docs invoke task) that produces MDX reference pages for infrahub_sdk.client and infrahub_sdk.node with auto-discovery validation ensuring every new package is explicitly categorized
• Documentation generation refactoring IHS-201: Extracted the monolithic tasks.py functions into a docs/docs_generation/ package with a Strategy pattern — ADocContentGenMethod (base), Jinja2DocContentGenMethod, CommandOutputDocContentGenMethod, FilePrintingDocContentGenMethod — composed via DocPage/MDXDocPage page objects
• Dynamic Docusaurus sidebars [IHS-200]: Replaced static sidebars-infrahubctl.ts and sidebars-python-sdk.ts with filesystem-reading versions in docs/sidebars/, using shared utility functions (getCommandItems, getItemsWithOrder) with vitest tests
• New "Python SDK API" sidebar section [IHS-198]: Added sdk_ref autogenerated category under Reference in the Python SDK sidebar
• Enhanced CI docs-validate check [IHS-197]: Now detects modified, deleted, and new untracked files under docs/ with descriptive error messages

What stayed the same

• All public SDK APIs unchanged
• Existing doc content (guides, topics, reference/config, reference/templating, infrahubctl commands) regenerated identically.

Suggested review order

This group of commits is a mixed between:

• Legacy work which has been squashed into meaningful sets of change
• Enhancement and completion of each part of the work.

One can refer to the internal issue key IHS-<insert_key> to only focus on changes that are tied to the same initial need.
Speaking about the reviewing order, I would suggest:

1. docs/docs_generation/ IHS-201: the new generation architecture (Strategy pattern on documentation generation methods + Page objects) -> Design decisions
   2.tasks.pyrefactoring IHS-201: how the new classes are wired into _generate_infrahub_sdk_configuration_documentation and _generate_infrahub_sdk_template_documentation -> Apply the refactoring
2. tasks.py API docs generation IHS-196: _generate_sdk_api_docs -> New feature
3. dynamic sidebar logic and tests [IHS-200]: docs/sidebars/ -> Enhance existing documentation
4. new "Python SDK API" sidebar section [IHS-198]: docs/sidebars/ -> New documentation
5. new CI check docs-validate [IHS-197]: docs_validate -> Documentation integrity

How to test

# Unit tests for doc generation
uv run pytest tests/unit/doc_generation/ -v

# Sidebar utility tests (vitest)
cd docs && npm test

# Full documentation generation
uv run invoke docs-generate

# CI validation check (should pass with no diff)
uv run invoke docs-validate

# Lint
uv run invoke format lint

Impact & rollout

• Backward compatibility: No breaking changes. All existing invoke tasks still work.
• Performance: No runtime impact -> changes only affect doc generation tooling.
• Config/env changes: New dev dependency mdxify in pyproject.toml, vitest in docs/package.json.
• Deployment notes: "To complete"

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 95.93909% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
infrahub_sdk/template/jinja2/__init__.py	95.58%	3 Missing and 3 partials ⚠️
infrahub_sdk/template/base.py	83.33%	0 Missing and 1 partial ⚠️
infrahub_sdk/template/jinja2/exceptions.py	96.00%	1 Missing ⚠️

@@             Coverage Diff             @@
##           develop     #822      +/-   ##
===========================================
+ Coverage    80.34%   80.37%   +0.03%     
===========================================
  Files          115      120       +5     
  Lines         9873     9896      +23     
  Branches      1504     1505       +1     
===========================================
+ Hits          7932     7954      +22     
  Misses        1420     1420              
- Partials       521      522       +1     

Flag	Coverage Δ
integration-tests	41.31% <0.00%> (-0.10%)	⬇️
python-3.10	51.34% <58.88%> (-0.04%)	⬇️
python-3.11	51.34% <58.88%> (-0.04%)	⬇️
python-3.12	51.34% <58.88%> (-0.06%)	⬇️
python-3.13	51.34% <58.88%> (-0.06%)	⬇️
python-3.14	52.98% <60.41%> (-0.07%)	⬇️
python-filler-3.12	24.17% <51.26%> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/ctl/utils.py	68.53% <ø> (ø)
infrahub_sdk/jinja2.py	0.00% <ø> (ø)
infrahub_sdk/pytest_plugin/items/base.py	78.37% <ø> (ø)
infrahub_sdk/template/__init__.py	100.00% <100.00%> (+4.44%)	⬆️
infrahub_sdk/template/exceptions.py	100.00% <100.00%> (+4.00%)	⬆️
infrahub_sdk/template/filters.py	100.00% <100.00%> (ø)
infrahub_sdk/template/jinja2/filters.py	100.00% <100.00%> (ø)
infrahub_sdk/template/jinja2/models.py	100.00% <100.00%> (ø)
infrahub_sdk/template/models.py	100.00% <100.00%> (ø)
infrahub_sdk/template/base.py	83.33% <83.33%> (ø)
... and 2 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.