#201 / IHS-194: Generate SDK API documentation

.github/workflows/ci.yml

@@ -173,7 +173,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
@@ -216,7 +216,6 @@ jobs:
         run: uv sync --all-groups --all-extras
       - name: Validate generated documentation
         run: uv run invoke docs-validate
-
   validate-documentation-style:
     if: |
       always() && !cancelled() &&
@@ -233,6 +232,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,8 @@ 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'
 
 jobs:
   sync:

changelog/201.added.md

@@ -0,0 +1 @@
+Add support for automatic Python SDK API from docstrings 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 />