From a5548c71abc5529704aa061a7702d46e4afb7721 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Wed, 8 Jul 2026 16:04:31 +0800 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Add=20MkDocs=20mac?= =?UTF-8?q?ro=20metadata=20adapter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds mkdocs-macros-plugin to the docs dependency group only (not runtime), adds docs_macros.py that reads pyproject.toml via tomllib and exposes an `aa` variable to Markdown pages, and enables the plugin in mkdocs.yml with `on_undefined: strict` + `on_error_fail: true` so undefined `{{ aa.* }}` references fail the strict build. Refs AAASM-4308. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs_macros.py | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 10 ++++++++ pyproject.toml | 3 +++ uv.lock | 53 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 135 insertions(+) create mode 100644 docs_macros.py diff --git a/docs_macros.py b/docs_macros.py new file mode 100644 index 0000000..c01429f --- /dev/null +++ b/docs_macros.py @@ -0,0 +1,69 @@ +"""MkDocs macro adapter for the Python SDK docs (AAASM-4308). + +Sources shared, drift-prone metadata (package version, package/import/CLI +names, canonical URLs, install commands) from a single source of truth and +exposes it to Markdown pages as an ``aa`` variable via ``mkdocs-macros-plugin``. + +The primary source of truth is ``pyproject.toml`` (via :mod:`tomllib`); values +that are cross-repo product metadata (canonical URLs, install commands, CLI +name, import name) live in the ``aa`` dict below and are the maintainer-facing +knob for any new shared value. + +Adding a new shared value +------------------------- + +1. Add the value under the appropriate section of ``aa`` in ``define_env`` + (``python_sdk`` for package-authoritative facts, ``urls`` for canonical + URLs, ``commands`` for install / CLI snippets). +2. Reference it from Markdown as ``{{ aa.
. }}``. +3. Do not template historical release notes / changelog entries — those + values are historical facts and must remain literal. + +Fail-fast behavior +------------------ + +``mkdocs.yml`` enables the macros plugin with ``on_undefined: strict`` and +``on_error_fail: true`` so an undefined ``{{ aa.* }}`` reference fails the +docs build under ``mkdocs build --strict`` instead of rendering as an empty +string. +""" + +from __future__ import annotations + +import tomllib +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parent + + +def define_env(env: Any) -> None: + """Register the shared ``aa`` metadata variable on the macros env. + + Called by ``mkdocs-macros-plugin`` at build time. See module docstring + for the maintainer contract when adding new shared values. + """ + pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text()) + project = pyproject["project"] + + aa: dict[str, dict[str, str]] = { + "python_sdk": { + "package_name": project["name"], + "version": project["version"], + "requires_python": project["requires-python"], + "import_name": "agent_assembly", + "cli_name": "aasm", + }, + "urls": { + "docs": "https://docs.agent-assembly.com/python-sdk/", + "repo": "https://github.com/ai-agent-assembly/python-sdk", + "pypi": "https://pypi.org/project/agent-assembly/", + }, + "commands": { + "install_uv": "uv add agent-assembly", + "install_pip": "pip install agent-assembly", + "install_pip_runtime": "pip install 'agent-assembly[runtime]'", + }, + } + + env.variables["aa"] = aa diff --git a/mkdocs.yml b/mkdocs.yml index 7b50314..8784d88 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,16 @@ theme: plugins: # Built-in client-side search — restores the search bar in the rendered site. - search + # AAASM-4308: shared metadata macros. Reads pyproject.toml (via docs_macros.py) + # and exposes an `aa` variable to Markdown pages so version/install/URL literals + # are sourced from a single place. `on_undefined: strict` + `on_error_fail: true` + # makes an unknown `{{ aa.* }}` reference fail the strict build instead of + # silently rendering empty. Placed before mkdocstrings so macros are expanded + # before docstring blocks render. + - macros: + module_name: docs_macros + on_error_fail: true + on_undefined: strict # Doc-as-Code — render Python API reference inline from package docstrings. - mkdocstrings: handlers: diff --git a/pyproject.toml b/pyproject.toml index 2eda5fe..f68ee5f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -138,6 +138,9 @@ docs = [ "mkdocs-autorefs>=1.0.0,<2", "mkdocs-git-revision-date-localized-plugin>=1.2.0,<2", "mkdocs-git-authors-plugin>=0.9.0,<1", + # AAASM-4308: shared metadata macros for docs pages. Docs-only — MUST NOT + # be added to `[project].dependencies` (runtime install stays lean). + "mkdocs-macros-plugin>=1,<2", ] [tool.uv] diff --git a/uv.lock b/uv.lock index 0147891..2df542d 100644 --- a/uv.lock +++ b/uv.lock @@ -50,6 +50,7 @@ docs = [ { name = "mkdocs-autorefs" }, { name = "mkdocs-git-authors-plugin" }, { name = "mkdocs-git-revision-date-localized-plugin" }, + { name = "mkdocs-macros-plugin" }, { name = "mkdocs-material" }, { name = "mkdocstrings" }, { name = "mkdocstrings-python" }, @@ -125,6 +126,7 @@ docs = [ { name = "mkdocs-autorefs", specifier = ">=1.0.0,<2" }, { name = "mkdocs-git-authors-plugin", specifier = ">=0.9.0,<1" }, { name = "mkdocs-git-revision-date-localized-plugin", specifier = ">=1.2.0,<2" }, + { name = "mkdocs-macros-plugin", specifier = ">=1,<2" }, { name = "mkdocs-material", specifier = ">=9.5.0,<10" }, { name = "mkdocstrings", specifier = ">=0.24.0,<2" }, { name = "mkdocstrings-python", specifier = ">=1.10.0,<3" }, @@ -1542,6 +1544,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/8a/7c/44314ecd0e89f8b2b51c9d9e5e7a60a9c1c82024ac471d415860557d3cd8/hf_xet-1.4.3-cp37-abi3-win_arm64.whl", hash = "sha256:7c2c7e20bcfcc946dc67187c203463f5e932e395845d098cc2a93f5b67ca0b47", size = 3533664, upload-time = "2026-03-31T22:40:12.152Z" }, ] +[[package]] +name = "hjson" +version = "3.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/82/e5/0b56d723a76ca67abadbf7fb71609fb0ea7e6926e94fcca6c65a85b36a0e/hjson-3.1.0.tar.gz", hash = "sha256:55af475a27cf83a7969c808399d7bccdec8fb836a07ddbd574587593b9cdcf75", size = 40541, upload-time = "2022-08-13T02:53:01.919Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1f/7f/13cd798d180af4bf4c0ceddeefba2b864a63c71645abc0308b768d67bb81/hjson-3.1.0-py3-none-any.whl", hash = "sha256:65713cdcf13214fb554eb8b4ef803419733f4f5e551047c9b711098ab7186b89", size = 54018, upload-time = "2022-08-13T02:52:59.899Z" }, +] + [[package]] name = "hpack" version = "4.1.0" @@ -2371,6 +2382,27 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/4b/3f/4f663fb7e889fbb2fabef7a67ddd96f8355edca917aa724c6c6cda352d01/mkdocs_git_revision_date_localized_plugin-1.5.1-py3-none-any.whl", hash = "sha256:b00fd36ed0f9b2326b1488fd8fa31bf2ce64e68c4aa60a9ce857f10719571903", size = 26150, upload-time = "2026-01-26T13:34:28.768Z" }, ] +[[package]] +name = "mkdocs-macros-plugin" +version = "1.5.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "hjson" }, + { name = "jinja2" }, + { name = "mkdocs" }, + { name = "packaging" }, + { name = "pathspec" }, + { name = "python-dateutil" }, + { name = "pyyaml" }, + { name = "requests" }, + { name = "super-collections" }, + { name = "termcolor" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/92/15/e6a44839841ebc9c5872fa0e6fad1c3757424e4fe026093b68e9f386d136/mkdocs_macros_plugin-1.5.0.tar.gz", hash = "sha256:12aa45ce7ecb7a445c66b9f649f3dd05e9b92e8af6bc65e4acd91d26f878c01f", size = 37730, upload-time = "2025-11-13T08:08:55.545Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/51/62/9fffba5bb9ed3d31a932ad35038ba9483d59850256ee0fea7f1187173983/mkdocs_macros_plugin-1.5.0-py3-none-any.whl", hash = "sha256:c10fabd812bf50f9170609d0ed518e54f1f0e12c334ac29141723a83c881dd6f", size = 44626, upload-time = "2025-11-13T08:08:53.878Z" }, +] + [[package]] name = "mkdocs-material" version = "9.7.6" @@ -4175,6 +4207,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" }, ] +[[package]] +name = "super-collections" +version = "0.6.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "hjson" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e0/de/a0c3d1244912c260638f0f925e190e493ccea37ecaea9bbad7c14413b803/super_collections-0.6.2.tar.gz", hash = "sha256:0c8d8abacd9fad2c7c1c715f036c29f5db213f8cac65f24d45ecba12b4da187a", size = 31315, upload-time = "2025-09-30T00:37:08.067Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/17/43/47c7cf84b3bd74a8631b02d47db356656bb8dff6f2e61a4c749963814d0d/super_collections-0.6.2-py3-none-any.whl", hash = "sha256:291b74d26299e9051d69ad9d89e61b07b6646f86a57a2f5ab3063d206eee9c56", size = 16173, upload-time = "2025-09-30T00:37:07.104Z" }, +] + [[package]] name = "temporalio" version = "1.28.0" @@ -4203,6 +4247,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/d7/c1/eb8f9debc45d3b7918a32ab756658a0904732f75e555402972246b0b8e71/tenacity-9.1.4-py3-none-any.whl", hash = "sha256:6095a360c919085f28c6527de529e76a06ad89b23659fa881ae0649b867a9d55", size = 28926, upload-time = "2026-02-07T10:45:32.24Z" }, ] +[[package]] +name = "termcolor" +version = "3.3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/46/79/cf31d7a93a8fdc6aa0fbb665be84426a8c5a557d9240b6239e9e11e35fc5/termcolor-3.3.0.tar.gz", hash = "sha256:348871ca648ec6a9a983a13ab626c0acce02f515b9e1983332b17af7979521c5", size = 14434, upload-time = "2025-12-29T12:55:21.882Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/33/d1/8bb87d21e9aeb323cc03034f5eaf2c8f69841e40e4853c2627edf8111ed3/termcolor-3.3.0-py3-none-any.whl", hash = "sha256:cf642efadaf0a8ebbbf4bc7a31cec2f9b5f21a9f726f4ccbb08192c9c26f43a5", size = 7734, upload-time = "2025-12-29T12:55:20.718Z" }, +] + [[package]] name = "tiktoken" version = "0.13.0" From d13d3dfae5b5f72f18046a96a35491a7adb337ce Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Wed, 8 Jul 2026 16:11:47 +0800 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Replace=20Python?= =?UTF-8?q?=20SDK=20version=20and=20install=20literals=20with=20macros?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Route the current SDK version, PyPI URL, docs URL, repo URL, import name, CLI name, and pip/uv install commands through the `aa` macro variable on the main user-facing pages (quick-start, compatibility index, release process, examples runtime environment). Historical release notes and per-release adapter/version tables are left literal — they describe historical facts, not current state. Refs AAASM-4308. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/compatibility/index.md | 7 ++++--- docs/compatibility/release-process.md | 11 ++++++----- .../preparing-the-runtime-environment.md | 6 +++--- docs/quick-start.md | 18 ++++++++++-------- 4 files changed, 23 insertions(+), 19 deletions(-) diff --git a/docs/compatibility/index.md b/docs/compatibility/index.md index b4a1bec..792f856 100644 --- a/docs/compatibility/index.md +++ b/docs/compatibility/index.md @@ -14,9 +14,10 @@ core runtime does a given SDK build talk to?*, and *how do versions and releases The SDK is **pre-1.0 (`0.x`)**. It is published and usable, but the public API is not yet frozen: until `1.0.0`, minor versions may carry breaking changes. If you need a stable -contract, **pin an exact version** (`agent-assembly==0.0.x`). From `1.0.0` onward the project -follows [SemVer](https://semver.org/). The canonical version lives in `pyproject.toml` -(`[project].version`) and is mirrored in `agent_assembly.__version__`. +contract, **pin an exact version** (`{{ aa.python_sdk.package_name }}=={{ aa.python_sdk.version }}`). +From `1.0.0` onward the project follows [SemVer](https://semver.org/). The canonical version +lives in `pyproject.toml` (`[project].version`) and is mirrored in +`{{ aa.python_sdk.import_name }}.__version__`. ## Core ↔ SDK compatibility matrix diff --git a/docs/compatibility/release-process.md b/docs/compatibility/release-process.md index 8ed6b10..3277c5c 100644 --- a/docs/compatibility/release-process.md +++ b/docs/compatibility/release-process.md @@ -20,8 +20,9 @@ wheel by platform tag, no post-install scripts needed: | `agent_assembly--…-macosx_*_arm64.whl` / `…x86_64.whl` | SDK + macOS `aasm` binary | | `agent_assembly-.tar.gz` (sdist) | Pure-Python source | -`pip install agent-assembly` gets the pure-Python client; `pip install 'agent-assembly[runtime]'` -pulls the platform wheel that bundles the binary. See [Installation](https://github.com/ai-agent-assembly/python-sdk#installation). +`{{ aa.commands.install_pip }}` gets the pure-Python client; +`{{ aa.commands.install_pip_runtime }}` pulls the platform wheel that bundles the binary. +See [Installation]({{ aa.urls.repo }}#installation). ## Publishing: Trusted Publisher (OIDC) @@ -39,16 +40,16 @@ dry-run without publishing. 2. Land it on `master` through the normal PR flow. 3. Push the release tag — the workflow builds every platform wheel + sdist and publishes them to PyPI via the Trusted Publisher. -4. Verify the wheels appear on the [PyPI release page](https://pypi.org/project/agent-assembly/#history) +4. Verify the wheels appear on the [PyPI release page]({{ aa.urls.pypi }}#history) and carry platform tags (`manylinux_*`, `macosx_*`), not `none-any`. ## Documentation versioning Docs are versioned with [`mike`](https://github.com/jimporter/mike): every push to `master` deploys to **`latest`**, and a release promotes to **`stable`**. Readers switch versions with -the selector at the top of the [documentation site](https://docs.agent-assembly.com/python-sdk/). +the selector at the top of the [documentation site]({{ aa.urls.docs }}). ## Release notes Release notes are tracked on the [Release notes](release-notes.md) page and the -[GitHub releases](https://github.com/ai-agent-assembly/python-sdk/releases) feed. +[GitHub releases]({{ aa.urls.repo }}/releases) feed. diff --git a/docs/examples/preparing-the-runtime-environment.md b/docs/examples/preparing-the-runtime-environment.md index 38931b9..09f7362 100644 --- a/docs/examples/preparing-the-runtime-environment.md +++ b/docs/examples/preparing-the-runtime-environment.md @@ -23,11 +23,11 @@ specific to that example. ## Install the SDK -Each example declares `agent-assembly` as a dependency, so `uv sync` (below) pulls it in. -To install the SDK on its own in your own project: +Each example declares `{{ aa.python_sdk.package_name }}` as a dependency, so `uv sync` +(below) pulls it in. To install the SDK on its own in your own project: ```bash -pip install agent-assembly +{{ aa.commands.install_pip }} ``` Some examples need a framework extra alongside the SDK (for instance LangChain pulls in diff --git a/docs/quick-start.md b/docs/quick-start.md index 6c74335..2094353 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -7,24 +7,26 @@ mock LLM, so you need no API keys and no network access to the outside world. ## 1. Install The package is published on PyPI as -[`agent-assembly`](https://pypi.org/project/agent-assembly/). +[`{{ aa.python_sdk.package_name }}`]({{ aa.urls.pypi }}) (current version: +`{{ aa.python_sdk.version }}`). === "pip" ```bash - pip install agent-assembly # pure-Python SDK - pip install 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel) + {{ aa.commands.install_pip }} # pure-Python SDK + {{ aa.commands.install_pip_runtime }} # SDK + bundled aasm runtime binary (platform wheel) ``` === "uv" ```bash - uv add agent-assembly + {{ aa.commands.install_uv }} ``` -`agent-assembly` is the pure-Python client. `agent-assembly[runtime]` additionally pulls a -platform wheel (`manylinux`, `macosx`) that bundles the `aasm` gateway/runtime binary, so a -local gateway is available without a separate install. +`{{ aa.python_sdk.package_name }}` is the pure-Python client. +`{{ aa.python_sdk.package_name }}[runtime]` additionally pulls a platform wheel +(`manylinux`, `macosx`) that bundles the `{{ aa.python_sdk.cli_name }}` +gateway/runtime binary, so a local gateway is available without a separate install. ## 2. Point the SDK at a gateway @@ -48,7 +50,7 @@ local default port). This example imports LangChain alongside the SDK, so install both: ```bash -pip install agent-assembly langchain langchain-community +{{ aa.commands.install_pip }} langchain langchain-community ``` Then run: From 37ca6fd0146b16c79aba680daa6a36c54cba56a5 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Wed, 8 Jul 2026 16:41:42 +0800 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Add=20maintainer?= =?UTF-8?q?=20note=20for=20MkDocs=20shared=20metadata=20macros?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/development/docs-macros.md — a maintainer contract for the shared metadata / macros layer. Covers: - What the top-level `aa` variable is and where each subsection comes from (`pyproject.toml` for package facts; string literals in `docs_macros.py` for URLs, install commands, import / CLI names). - How to add a new shared value: edit `docs_macros.py`, reference it as `{{ aa.
. }}`, and rely on `on_undefined: strict` + `on_error_fail: true` under `mkdocs build --strict` (already run in CI via `.github/workflows/documentation.yaml`) to catch typos. - What NOT to template: historical release notes, per-release adapter tables, and pinning-pattern examples (`agent-assembly==0.0.x`) must stay literal. Links the new page from `docs/development/index.md` and adds it to the `Development` section of the nav in `mkdocs.yml`. Closes AAASM-4308. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/development/docs-macros.md | 119 ++++++++++++++++++++++++++++++++ docs/development/index.md | 1 + mkdocs.yml | 1 + 3 files changed, 121 insertions(+) create mode 100644 docs/development/docs-macros.md diff --git a/docs/development/docs-macros.md b/docs/development/docs-macros.md new file mode 100644 index 0000000..6f12174 --- /dev/null +++ b/docs/development/docs-macros.md @@ -0,0 +1,119 @@ +{% raw %} +# Shared metadata macros in the docs + +The Python SDK docs use [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/) +so that drift-prone factual values — the current package version, the PyPI / +repo / docs URLs, the import name, the CLI name, and canonical install +commands — live in **one source of truth** instead of being hand-copied across +Markdown pages. + +This page is the maintainer contract for that macro layer. Read it before +adding a new shared value or before editing `docs_macros.py`. + +## Where the values come from + +Every macro variable exposed to Markdown pages is registered in +[`docs_macros.py`](https://github.com/ai-agent-assembly/python-sdk/blob/master/docs_macros.py) +at the repo root and is available in Markdown as the top-level `aa` object. + +The layout is: + +| Section | What lives here | Source | +| --- | --- | --- | +| `aa.python_sdk` | Package version, package name, `requires-python`, import name, CLI name | `pyproject.toml` (via `tomllib`) for version / name / `requires-python`; string literals in `docs_macros.py` for the import and CLI names | +| `aa.urls` | Canonical docs, repo, and PyPI URLs | String literals in `docs_macros.py` | +| `aa.commands` | Install snippets (`pip install …`, `uv add …`, runtime extra) | String literals in `docs_macros.py` | + +The **package version is never hand-maintained in Markdown**. It is read from +`[project].version` in `pyproject.toml` at every docs build, so a release bump +to `pyproject.toml` automatically updates every page that references +`{{ aa.python_sdk.version }}`. + +## Adding a new shared value + +1. Open `docs_macros.py` at the repo root. +2. Add the value under the appropriate section of the `aa` dict inside + `define_env`: + - `python_sdk` — package-authoritative facts (prefer sourcing from + `pyproject.toml` where possible). + - `urls` — canonical URLs (docs, repo, PyPI, related sites). + - `commands` — install and CLI snippets. + + If none of these fit, add a new section rather than overloading an + existing one. +3. Reference it from any Markdown page as `{{ aa.
. }}`. +4. Run `uv run mkdocs build --strict` locally. Because `mkdocs.yml` sets + `on_undefined: strict` and `on_error_fail: true`, a typo in the variable + path fails the build immediately instead of silently rendering an empty + string. + +Example — adding a new URL: + +```python +# docs_macros.py +aa = { + ... + "urls": { + "docs": "https://docs.agent-assembly.com/python-sdk/", + "repo": "https://github.com/ai-agent-assembly/python-sdk", + "pypi": "https://pypi.org/project/agent-assembly/", + # new value: + "issues": "https://github.com/ai-agent-assembly/python-sdk/issues", + }, + ... +} +``` + +```markdown + +Report bugs on the [issue tracker]({{ aa.urls.issues }}). +``` + +## What NOT to template + +- **Historical release notes and per-release adapter tables** — a line like + ``| `agent-assembly` | `>=0.0.1rc3` (the release that ships the Haystack + adapter) |`` is a **historical fact** about which version first shipped a + feature. It must remain a literal so future readers can still see when that + feature landed. +- **Version-range examples** (e.g. `agent-assembly==0.0.x`) that illustrate a + pinning pattern rather than the current version. +- **One-off framework-composed install commands** where the readability cost + of `{{ aa.commands.install_pip }} langchain` exceeds the drift risk of + `pip install agent-assembly langchain`. Templating everything is not the + goal; the goal is to keep the **current-state, high-drift** values in sync. + +If in doubt, ask: *"When we cut the next release, will this line become +wrong if left alone?"* If yes, template it. If no, leave it literal. + +## Fail-fast behavior + +The plugin is configured in `mkdocs.yml` as: + +```yaml +- macros: + module_name: docs_macros + on_error_fail: true + on_undefined: strict +``` + +Combined with the CI job that runs `uv run mkdocs build --strict` in +`.github/workflows/documentation.yaml`, this means: + +- A typo like `{{ aa.python_sdk.versio }}` **fails the docs build** rather + than rendering as an empty string. +- A missing macro function or Python-side exception in `docs_macros.py` + **fails the docs build** rather than being logged and skipped. + +So CI is the safety net: if a macro reference is broken, the PR cannot merge +with a green docs check. + +## Related files + +- `docs_macros.py` — the macros module. +- `mkdocs.yml` — enables the plugin (search for `- macros:`). +- `pyproject.toml` — the version / package-name / `requires-python` source of + truth read by `docs_macros.py`. +- `.github/workflows/documentation.yaml` — the CI job that runs + `mkdocs build --strict`. +{% endraw %} diff --git a/docs/development/index.md b/docs/development/index.md index b9b330d..bf0a6fb 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -9,6 +9,7 @@ Agent Assembly Python SDK. Start here when contributing code or operating a rele | --- | --- | | [CONTRIBUTING.md](https://github.com/ai-agent-assembly/python-sdk/blob/master/CONTRIBUTING.md) | Dev environment setup, framework adapter authoring, test/lint commands, branch naming, PR checklist. | | [Architecture](../concepts/architecture.md) | Internals: the adapter/patch layers, the PyO3 FFI layer, and the exact `init_assembly()` bootstrap/teardown order. | +| [Docs macros (shared metadata)](docs-macros.md) | How the MkDocs macro variables (`aa.*`) work, how to add a new shared value, and what must stay literal. | | [Compatibility & Versioning](../compatibility/index.md) | Supported Python versions, core-runtime tracking, and the release process. | | [Troubleshooting](../troubleshooting.md) | Common integration errors, what they mean, and how to fix them. | diff --git a/mkdocs.yml b/mkdocs.yml index 8784d88..6a3915b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -271,5 +271,6 @@ nav: - Troubleshooting: troubleshooting.md - Development: - development/index.md + - Docs macros (shared metadata): development/docs-macros.md - ADR: - 0001 — Hook architecture: development/adr/0001-hook-architecture.md From 46c59790a1a121ff1201d178aad3da23caba2a65 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Wed, 8 Jul 2026 21:09:20 +0800 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Template=20require?= =?UTF-8?q?s-python=20literal=20in=20compatibility/runtime.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Python version cell in the "Python versions" table hardcoded `requires-python = ">=3.12,<4.0"` — a value that must stay in lockstep with pyproject.toml. Replace the literal with `{{ aa.python_sdk.requires_python }}` so the compatibility page sources the range from the AAASM-4308 shared metadata macros. Refs AAASM-4308. --- docs/compatibility/runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/compatibility/runtime.md b/docs/compatibility/runtime.md index e0a9611..275234c 100644 --- a/docs/compatibility/runtime.md +++ b/docs/compatibility/runtime.md @@ -7,7 +7,7 @@ Python versions it supports. | | | | --- | --- | -| Supported | Python **3.12, 3.13, 3.14** (`requires-python = ">=3.12,<4.0"`) | +| Supported | Python **3.12, 3.13, 3.14** (`requires-python = "{{ aa.python_sdk.requires_python }}"`) | | Tested in CI | 3.12 – 3.14 across Linux and macOS | The SDK uses modern typing (PEP 695 `type` aliases, PEP 604 unions), so 3.12 is the floor.