ci: add api doc generation

.github/workflows/ci.yml

@@ -54,7 +54,7 @@ jobs:
           token: ${{ github.token }}
           filters: .github/file-filters.yml
 
- # ------------------------------------------ All Linter  ------------------------------------------
+  # ------------------------------------------ All Linter  ------------------------------------------
 
   yaml-lint:
     if: needs.files-changed.outputs.yaml == 'true'
@@ -84,7 +84,6 @@ jobs:
       - name: "Linting: ruff format"
         run: "ruff format --check --diff ."
 
-
   markdown-lint:
     if: |
       needs.files-changed.outputs.documentation == 'true' ||
@@ -119,7 +118,6 @@ jobs:
         env:
           SHELLCHECK_OPTS: --exclude=SC2086 --exclude=SC2046 --exclude=SC2004 --exclude=SC2129
 
-
   documentation:
     defaults:
       run:
@@ -141,7 +139,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: 'npm'
+          cache: "npm"
           cache-dependency-path: docs/package-lock.json
       - name: "Install dependencies"
         run: npm install
@@ -180,6 +178,50 @@ jobs:
       - name: "Validate generated documentation"
         run: "poetry run invoke docs-validate"
 
+  check-api-documentation-obsolescence:
+    if: |
+      always() && !cancelled() &&
+      !contains(needs.*.result, 'failure') &&
+      !contains(needs.*.result, 'cancelled') &&
+      (needs.files-changed.outputs.python == 'true') || (needs.files-changed.outputs.documentation_generated == 'true')
+    needs: ["prepare-environment", "files-changed", "yaml-lint", "python-lint"]
+    runs-on: "ubuntu-22.04"
+    env:
+      DOCS_COMMAND: "poetry run invoke generate-sdk-api-docs"
+      SDK_API_DOCS_DIR: "docs/docs/python-sdk/sdk_ref"
+    timeout-minutes: 5
+    steps:
+      - name: "Check out repository code"
+        uses: "actions/checkout@v4"
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: "Setup Python environment"
+        run: |
+          pipx install poetry==${{ needs.prepare-environment.outputs.POETRY_VERSION }}
+          poetry config virtualenvs.create true --local
+          poetry env use 3.12
+      - name: "Install dependencies"
+        run: "poetry install --no-interaction --no-ansi --extras ctl"
+      - name: "Setup environment"
+        run: "pip install invoke toml"
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+          cache-dependency-path: "**/package-lock.json"
+      - name: Install markdown linter
+        run: npm install -g markdownlint-cli2
+      - name: "Generate SDK API documentation"
+        run: ${{ env.DOCS_COMMAND }}
+      - name: "Check if SDK API documentation needs to be refreshed"
+        run: |
+          git diff --quiet ${SDK_API_DOCS_DIR}
+
   validate-documentation-style:
     if: |
       always() && !cancelled() &&
@@ -203,7 +245,7 @@ jobs:
         env:
           VALE_VERSION: ${{ env.VALE_VERSION }}
       - name: "Validate documentation style"
-        run: ./vale $(find ./docs -type f \( -name "*.mdx" -o -name "*.md" \) )
+        run: ./vale $(find ./docs -type d -name sdk_ref -prune -false -o -type f \( -name "*.mdx" -o -name "*.md" \) )
 
   unit-tests:
     env:

changelog/201.added.md

@@ -0,0 +1 @@
+Add support for automatic Python SDK API from docstrings in the code.

docs/docs/python-sdk/sdk_ref/infrahub_sdk/analyzer.mdx

@@ -0,0 +1,68 @@
+---
+title: analyzer
+sidebarTitle: analyzer
+---
+
+# `infrahub_sdk.analyzer`
+
+## Classes
+
+### `GraphQLQueryVariable` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L20" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `GraphQLOperation` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L27" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `GraphQLQueryAnalyzer` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L32" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `is_valid` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L40" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+is_valid(self) -> tuple[bool, list[GraphQLError] | None]
+```
+
+#### `nbr_queries` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L51" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+nbr_queries(self) -> int
+```
+
+#### `operations` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+operations(self) -> list[GraphQLOperation]
+```
+
+#### `contains_mutation` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L68" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+contains_mutation(self) -> bool
+```
+
+#### `variables` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L72" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+variables(self) -> list[GraphQLQueryVariable]
+```
+
+#### `calculate_depth` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L101" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+calculate_depth(self) -> int
+```
+
+Number of nested levels in the query
+
+#### `calculate_height` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+calculate_height(self) -> int
+```
+
+Total number of fields requested in the query
+
+#### `get_fields` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/analyzer.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+get_fields(self) -> dict[str, Any]
+```

docs/docs/python-sdk/sdk_ref/infrahub_sdk/async_typer.mdx

@@ -0,0 +1,30 @@
+---
+title: async_typer
+sidebarTitle: async_typer
+---
+
+# `infrahub_sdk.async_typer`
+
+## Classes
+
+### `AsyncTyper` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/async_typer.py#L11" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `maybe_run_async` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/async_typer.py#L13" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+maybe_run_async(decorator: Callable, func: Callable) -> Any
+```
+
+#### `callback` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/async_typer.py#L25" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+callback(self, *args: Any, **kwargs: Any) -> Any
+```
+
+#### `command` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/async_typer.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+command(self, *args: Any, **kwargs: Any) -> Any
+```

docs/docs/python-sdk/sdk_ref/infrahub_sdk/batch.mdx

@@ -0,0 +1,74 @@
+---
+title: batch
+sidebarTitle: batch
+---
+
+# `infrahub_sdk.batch`
+
+## Functions
+
+### `execute_batch_task_in_pool` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L41" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+execute_batch_task_in_pool(task: BatchTask, semaphore: asyncio.Semaphore, return_exceptions: bool = False) -> tuple[InfrahubNode | None, Any]
+```
+
+## Classes
+
+### `BatchTask` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L14" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+### `BatchTaskSync` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L22" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `execute` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+execute(self, return_exceptions: bool = False) -> tuple[InfrahubNodeSync | None, Any]
+```
+
+Executes the stored task.
+
+### `InfrahubBatch` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L55" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `num_tasks` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L67" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+num_tasks(self) -> int
+```
+
+#### `add` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L70" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add(self, *args: Any, **kwargs: Any) -> None
+```
+
+#### `execute` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L73" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+execute(self) -> AsyncGenerator
+```
+
+### `InfrahubBatchSync` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+**Methods:**
+
+#### `num_tasks` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L99" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+num_tasks(self) -> int
+```
+
+#### `add` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L102" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+add(self, *args: Any, **kwargs: Any) -> None
+```
+
+#### `execute` <sup><a href="https://github.com/opsmill/infrahub-sdk-python/blob/main/infrahub_sdk/batch.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+execute(self) -> Generator[tuple[InfrahubNodeSync | None, Any], None, None]
+```