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

.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.

docs/AGENTS.md

@@ -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**
 

docs/_templates/sdk_config.j2

@@ -31,8 +31,6 @@ The following settings can be defined in the `Config` class
 {% for property in properties %}
 <!-- vale off -->
 ## {{ property.name }}
-
-**Property**: {{ property.name }}<br />
 <!-- vale on -->
 **Description**: {% if '\n' in property.description %} {% endif %}{{ property.description }}<br />
 **Type**: `{{ property.type }}`<br />

docs/docs/python-sdk/reference/config.mdx

@@ -30,189 +30,145 @@ The Python SDK (Async or Sync) client can be configured using an instance of the
 The following settings can be defined in the `Config` class
 <!-- vale off -->
 ## address
-
-**Property**: address<br />
 <!-- vale on -->
 **Description**: The URL to use when connecting to Infrahub.<br />
 **Type**: `string`<br />
 **Default value**: http://localhost:8000<br />
 **Environment variable**: `INFRAHUB_ADDRESS`<br />
 <!-- vale off -->
 ## api_token
-
-**Property**: api_token<br />
 <!-- vale on -->
 **Description**: API token for authentication against Infrahub.<br />
 **Type**: `string`<br />
 **Environment variable**: `INFRAHUB_API_TOKEN`<br />
 <!-- vale off -->
 ## echo_graphql_queries
-
-**Property**: echo_graphql_queries<br />
 <!-- vale on -->
 **Description**: If set the GraphQL query and variables will be echoed to the screen<br />
 **Type**: `boolean`<br />
 **Default value**: False<br />
 **Environment variable**: `INFRAHUB_ECHO_GRAPHQL_QUERIES`<br />
 <!-- vale off -->
 ## username
-
-**Property**: username<br />
 <!-- vale on -->
 **Description**: Username for accessing Infrahub<br />
 **Type**: `string`<br />
 **Environment variable**: `INFRAHUB_USERNAME`<br />
 <!-- vale off -->
 ## password
-
-**Property**: password<br />
 <!-- vale on -->
 **Description**: Password for accessing Infrahub<br />
 **Type**: `string`<br />
 **Environment variable**: `INFRAHUB_PASSWORD`<br />
 <!-- vale off -->
 ## default_branch
-
-**Property**: default_branch<br />
 <!-- vale on -->
 **Description**: Default branch to target if not specified for each request.<br />
 **Type**: `string`<br />
 **Default value**: main<br />
 **Environment variable**: `INFRAHUB_DEFAULT_BRANCH`<br />
 <!-- vale off -->
 ## default_branch_from_git
-
-**Property**: default_branch_from_git<br />
 <!-- vale on -->
 **Description**: Indicates if the default Infrahub branch to target should come from the active branch in the local Git repository.<br />
 **Type**: `boolean`<br />
 **Default value**: False<br />
 **Environment variable**: `INFRAHUB_DEFAULT_BRANCH_FROM_GIT`<br />
 <!-- vale off -->
 ## identifier
-
-**Property**: identifier<br />
 <!-- vale on -->
 **Description**: Tracker identifier<br />
 **Type**: `string`<br />
 **Environment variable**: `INFRAHUB_IDENTIFIER`<br />
 <!-- vale off -->
 ## insert_tracker
-
-**Property**: insert_tracker<br />
 <!-- vale on -->
 **Description**: Insert a tracker on queries to the server<br />
 **Type**: `boolean`<br />
 **Default value**: False<br />
 **Environment variable**: `INFRAHUB_INSERT_TRACKER`<br />
 <!-- vale off -->
 ## max_concurrent_execution
-
-**Property**: max_concurrent_execution<br />
 <!-- vale on -->
 **Description**: Max concurrent execution in batch mode<br />
 **Type**: `integer`<br />
 **Default value**: 5<br />
 **Environment variable**: `INFRAHUB_MAX_CONCURRENT_EXECUTION`<br />
 <!-- vale off -->
 ## mode
-
-**Property**: mode<br />
 <!-- vale on -->
 **Description**: Default mode for the client<br />
 **Type**: `object`<br />
 **Environment variable**: `INFRAHUB_MODE`<br />
 <!-- vale off -->
 ## pagination_size
-
-**Property**: pagination_size<br />
 <!-- vale on -->
 **Description**: Page size for queries to the server<br />
 **Type**: `integer`<br />
 **Default value**: 50<br />
 **Environment variable**: `INFRAHUB_PAGINATION_SIZE`<br />
 <!-- vale off -->
 ## retry_delay
-
-**Property**: retry_delay<br />
 <!-- vale on -->
 **Description**: Number of seconds to wait until attempting a retry.<br />
 **Type**: `integer`<br />
 **Default value**: 5<br />
 **Environment variable**: `INFRAHUB_RETRY_DELAY`<br />
 <!-- vale off -->
 ## retry_on_failure
-
-**Property**: retry_on_failure<br />
 <!-- vale on -->
 **Description**: Retry operation in case of failure<br />
 **Type**: `boolean`<br />
 **Default value**: False<br />
 **Environment variable**: `INFRAHUB_RETRY_ON_FAILURE`<br />
 <!-- vale off -->
 ## max_retry_duration
-
-**Property**: max_retry_duration<br />
 <!-- vale on -->
 **Description**: Maximum duration until we stop attempting to retry if enabled.<br />
 **Type**: `integer`<br />
 **Default value**: 300<br />
 **Environment variable**: `INFRAHUB_MAX_RETRY_DURATION`<br />
 <!-- vale off -->
 ## schema_converge_timeout
-
-**Property**: schema_converge_timeout<br />
 <!-- vale on -->
 **Description**: Number of seconds to wait for schema to have converged<br />
 **Type**: `integer`<br />
 **Default value**: 60<br />
 **Environment variable**: `INFRAHUB_SCHEMA_CONVERGE_TIMEOUT`<br />
 <!-- vale off -->
 ## timeout
-
-**Property**: timeout<br />
 <!-- vale on -->
 **Description**: Default connection timeout in seconds<br />
 **Type**: `integer`<br />
 **Default value**: 60<br />
 **Environment variable**: `INFRAHUB_TIMEOUT`<br />
 <!-- vale off -->
 ## transport
-
-**Property**: transport<br />
 <!-- vale on -->
 **Description**: Set an alternate transport using a predefined option<br />
 **Type**: `object`<br />
 **Environment variable**: `INFRAHUB_TRANSPORT`<br />
 <!-- vale off -->
 ## proxy
-
-**Property**: proxy<br />
 <!-- vale on -->
 **Description**: Proxy address<br />
 **Type**: `string`<br />
 **Environment variable**: `INFRAHUB_PROXY`<br />
 <!-- vale off -->
 ## proxy_mounts
-
-**Property**: proxy_mounts<br />
 <!-- vale on -->
 **Description**: Proxy mounts configuration<br />
 **Type**: `object`<br />
 **Environment variable**: `INFRAHUB_PROXY_MOUNTS`<br />
 <!-- vale off -->
 ## update_group_context
-
-**Property**: update_group_context<br />
 <!-- vale on -->
 **Description**: Update GraphQL query groups<br />
 **Type**: `boolean`<br />
 **Default value**: False<br />
 **Environment variable**: `INFRAHUB_UPDATE_GROUP_CONTEXT`<br />
 <!-- vale off -->
 ## tls_insecure
-
-**Property**: tls_insecure<br />
 <!-- vale on -->
 **Description**:  
     Indicates if TLS certificates are verified.
@@ -223,8 +179,6 @@ The following settings can be defined in the `Config` class
 **Environment variable**: `INFRAHUB_TLS_INSECURE`<br />
 <!-- vale off -->
 ## tls_ca_file
-
-**Property**: tls_ca_file<br />
 <!-- vale on -->
 **Description**: File path to CA cert or bundle in PEM format<br />
 **Type**: `string`<br />