Merge pull request #840 from opsmill/merge-822-832-833-develop-to-infrahub-develop

Merge SDK API documentation PRs 822 832 833 develop to infrahub develop

Author: polmichel

.github/file-filters.yml

@@ -36,7 +36,8 @@ markdown_all: &markdown_all
 
 infrahub_reference_generated: &infrahub_reference_generated
   - "docs/docs/infrahubctl/*.mdx"
-  - "docs/docs/python-sdk/reference/config.mdx"
+  - "docs/docs/python-sdk/reference/*.mdx"
+  - "docs/docs/python-sdk/sdk_ref/**/*.mdx"
 
 documentation_all:
   - *development_files

.github/workflows/ci.yml

@@ -108,7 +108,7 @@ jobs:
       - name: "Linting: markdownlint"
         uses: DavidAnson/markdownlint-cli2-action@v22
         with:
-          config: .markdownlint.yaml
+          config: docs/.markdownlint.yaml
           globs: |
             **/*.{md,mdx}
             !changelog/*.md
@@ -176,7 +176,7 @@ jobs:
         uses: actions/setup-node@v5
         with:
           node-version: 20
-          cache: 'npm'
+          cache: "npm"
           cache-dependency-path: docs/package-lock.json
       - name: "Install dependencies"
         run: npm install
@@ -207,6 +207,15 @@ jobs:
         uses: "actions/checkout@v6"
         with:
           submodules: true
+      - name: Install NodeJS
+        uses: actions/setup-node@v5
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+      - name: "Install npm dependencies"
+        run: npm install
+        working-directory: ./docs
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
@@ -217,9 +226,11 @@ jobs:
           version: "${{ needs.prepare-environment.outputs.UV_VERSION }}"
       - name: Install dependencies
         run: uv sync --all-groups --all-extras
+      - name: Docs unit tests
+        run: npx --no-install vitest run
+        working-directory: ./docs
       - name: Validate generated documentation
         run: uv run invoke docs-validate
-
   validate-documentation-style:
     if: |
       always() && !cancelled() &&
@@ -236,6 +247,7 @@ jobs:
 
       # The official GitHub Action for Vale doesn't work, installing manually instead:
       # https://github.com/errata-ai/vale-action/issues/103
+      # cf -> https://github.com/nf-core/website/pull/3509
       - name: Download Vale
         run: |
           curl -sL "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz" -o vale.tar.gz

.github/workflows/sync-docs.yml

@@ -8,8 +8,9 @@ on:
       - stable
     paths:
       - 'docs/docs/**'
-      - 'docs/sidebars-infrahubctl.ts'
-      - 'docs/sidebars-python-sdk.ts'
+      - 'docs/sidebars/sidebars-infrahubctl.ts'
+      - 'docs/sidebars/sidebars-python-sdk.ts'
+      - 'docs/sidebars/sidebar-utils.ts'
 
 jobs:
   sync:
@@ -33,8 +34,9 @@ jobs:
           rm -f target-repo/docs/sidebars-python-sdk.ts
           rm -f target-repo/docs/sidebars-infrahubctl.ts
           cp -r source-repo/docs/docs/* target-repo/docs/docs-python-sdk/
-          cp source-repo/docs/sidebars-infrahubctl.ts target-repo/docs/
-          cp source-repo/docs/sidebars-python-sdk.ts target-repo/docs/
+          cp source-repo/docs/sidebars/sidebars-infrahubctl.ts target-repo/docs/
+          cp source-repo/docs/sidebars/sidebars-python-sdk.ts target-repo/docs/
+          cp source-repo/docs/sidebars/sidebar-utils.ts target-repo/docs/
           cd target-repo
           git config user.name github-actions
           git config user.email github-actions@github.com

.vale.ini

@@ -23,3 +23,10 @@ BasedOnStyles =
 
 [*]
 BasedOnStyles = Infrahub
+
+# Generated API reference docs: use GeneratedRef spelling (allows snake_case)
+# instead of global Infrahub spelling. Must be last to override [*].
+[docs/docs/python-sdk/sdk_ref/**/*.mdx]
+BasedOnStyles = Infrahub, GeneratedRef
+Infrahub.spelling = NO
+BlockIgnores = (?s) *((import.*?\n)|(```.*?```\n))

.vale/styles/GeneratedRef/spelling.yml

@@ -0,0 +1,10 @@
+---
+extends: spelling
+message: "Did you really mean '%s'?"
+level: error
+filters:
+  - '[pP]y.*\b'
+  - '\bimport_.*\b' # Ignore variables starting with 'import_'
+  - '\w+__value' # Skip Infrahub filters in documentation (name__value)
+  - '\b\w+_\w+\b' # Ignore snake_case identifiers in generated API reference docs
+ignore: spelling-exceptions.txt

.vale/styles/Infrahub/spelling.yml

@@ -4,6 +4,6 @@ message: "Did you really mean '%s'?"
 level: error
 filters:
   - '[pP]y.*\b'
-  - '\bimport_.*\b' # New filter to ignore variables starting with 'import_'
-  - '\w+__value' # New filter to skip Infrahub filters in documentation (name__value)
+  - '\bimport_.*\b' # Ignore variables starting with 'import_'
+  - '\w+__value' # Skip Infrahub filters in documentation (name__value)
 ignore: spelling-exceptions.txt

.vale/styles/spelling-exceptions.txt

@@ -3,6 +3,7 @@ Alibaba
 Ansible
 append_git_suffix
 APIs
+Args
 artifact_definitions
 artifact_name
 async

changelog/201.added.md

@@ -0,0 +1 @@
+Python SDK API documentation is now generated directly from the docstrings of the classes, functions, and methods contained in the code.

.markdownlint.yaml docs/.markdownlint.yaml.markdownlint.yaml renamed to docs/.markdownlint.yaml

@@ -8,8 +8,10 @@ Docusaurus documentation following Diataxis framework.
 cd docs && npm install              # Install deps
 cd docs && npm start                # Dev server at localhost:3000
 cd docs && npm run build            # Build static site
-uv run invoke docs                  # Generate auto-docs
-uv run invoke docs-validate         # Validate docs are current
+cd docs && npm test                 # Run sidebar utility tests
+uv run invoke docs                  # Build documentation website
+uv run invoke docs-generate         # Regenerate all docs (infrahubctl CLI + Python SDK)
+uv run invoke docs-validate         # Check that generated docs match committed files
 ```
 
 ## Structure
@@ -23,11 +25,19 @@ docs/docs/
 └── infrahubctl/     # CLI docs (auto-generated)
 ```
 
+## Sidebars
+
+Sidebar navigation is dynamic: `sidebars-*.ts` files read the filesystem at build time via utility functions in `sidebar-utils.ts`.
+
+- **infrahubctl**: all `.mdx` files are discovered automatically and sorted alphabetically.
+- **python-sdk**: guides, topics, and reference sections preserve a defined display order; new files are appended alphabetically at the end.
+
+No manual sidebar update is needed when adding a new `.mdx` file. However, to control the display order of a new page, add its doc ID to the ordered list in the corresponding `sidebars-*.ts` file.
+
 ## Adding Documentation
 
 1. Create MDX file in appropriate directory
 2. Add frontmatter with `title`
-3. Update `sidebars-*.ts` for navigation
 
 ## MDX Pattern
 
@@ -52,7 +62,7 @@ Use callouts for important notes.
 ✅ **Always**
 
 - Include both async/sync examples using Tabs
-- Run `uv run invoke docs-validate` after code changes
+- Run `uv run invoke docs-validate` after code changes to verify generated docs are up to date
 
 🚫 **Never**