fix(docs): fix broken API reference page on ReadTheDocs#453
fix(docs): fix broken API reference page on ReadTheDocs#453omid-aignostics wants to merge 4 commits intomainfrom
Conversation
…output
Using the default width=80 in yaml.dump caused long strings to wrap at
column 80. Some continuation words landed at column 0, making the
generated openapi_v1.yaml invalid YAML. This caused widdershins to fail
silently and produce garbage markdown in API_REFERENCE_v1.md.
Fix by passing width=float("inf") to disable line wrapping, and using
print() instead of console.print() to avoid Rich applying a second
layer of wrapping on output.
Regenerate openapi_v1.yaml, API_REFERENCE_v1.md, CLI_REFERENCE.md and
README.md.
[skip:ci, skip:test:long-running, skip:test:matrix-runner, skip:test:very-long-running]
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[skip:ci, skip:test:long-running, skip:test:matrix-runner, skip:test:very-long-running] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
[skip:ci, skip:test:long-running, skip:test:matrix-runner, skip:test:very-long-running] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR fixes broken ReadTheDocs rendering of the v1 API reference by ensuring the generated OpenAPI YAML is valid (no line-wrapping that breaks YAML parsing), and regenerates the derived API reference Markdown.
Changes:
- Update
aignostics system openapi --output-format=yamlto emit unwrapped YAML to stdout. - Regenerate
docs/source/_static/openapi_v1.yamlandAPI_REFERENCE_v1.mdfrom the corrected OpenAPI YAML. - Minor docs maintenance updates (RST include formatting, CLI reference output, misc formatting/whitespace).
Reviewed changes
Copilot reviewed 5 out of 16 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/aignostics/system/_cli.py | Adjust YAML dumping/printing for OpenAPI export to prevent wrap-induced invalid YAML. |
| docs/source/security.rst | Minor include directive formatting. |
| docs/source/release-notes.rst | Minor include directive formatting. |
| docs/source/platform_overview.rst | Minor include directive formatting. |
| docs/source/operational_excellence.rst | Minor include directive formatting. |
| docs/source/license.rst | Minor include directive formatting. |
| docs/source/glossary.rst | Minor include directive formatting. |
| docs/source/cli_reference.rst | Minor include directive formatting. |
| docs/source/attributions.rst | Minor include directive formatting. |
| docs/source/api_reference_v1.rst | Minor include directive formatting. |
| docs/source/_static/openapi_v1.yaml | Regenerated OpenAPI YAML with long strings no longer wrapped into invalid YAML. |
| README.md | Adds an MCP Server section to the interface overview. |
| CLI_REFERENCE.md | Regenerated CLI reference output (notably GPU default now A100). |
| CHANGELOG.md | Removes trailing blank lines. |
| API_REFERENCE_v1.md | Regenerated API reference output from OpenAPI via Widdershins. |
| .license-types-allowed | Formatting/indentation fix for license entry list. |
| ### 🤖 MCP Server (AI Agent Integration) | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **What it is** | Model Context Protocol server that exposes SDK functionality to AI agents like Claude | | ||
| | **Best for** | Users who want AI assistants to help with platform operations | | ||
| | **Use when** | Working with Claude Desktop or other MCP-compatible AI tools to manage datasets, submit runs, or query results | | ||
| | **Get started** | <a href="#mcp-server-integrate-with-ai-agents">Configure Claude Desktop for MCP integration</a> | | ||
|
|
There was a problem hiding this comment.
README.md is generated from docs partials during the docs build (see noxfile.py generate_readme). Direct edits here are likely to be overwritten the next time docs are regenerated; please apply this change in the appropriate docs/partials/README*.md source instead and re-generate README.md.
API_REFERENCE_v1.md
Outdated
| <!-- Generator: Widdershins v4.0.1 --> | ||
|
|
||
| <h1 id="aignostics-platform-api">Aignostics Platform API v1.0.0-ga</h1> | ||
|
|
||
| > Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu. |
There was a problem hiding this comment.
API_REFERENCE_v1.md appears to be committed as raw Widdershins output (HTML headings/anchors still present). The repo’s docs generation pipeline post-processes Widdershins output (see noxfile.py _generate_api_reference) and would produce a different, cleaned Markdown file; please regenerate via the standard docs task (or adjust the post-processing if the new raw format is intended) so the committed artifact matches the documented generation process.
…ssing Widdershins produces HTML headings when given JSON input (which the noxfile post-processing is designed to handle), but Slate front matter when given YAML input. Switch widdershins input from openapi_v1.yaml to openapi_v1.json so the generated API_REFERENCE_v1.md matches the documented pipeline and renders correctly. Regenerate API_REFERENCE_v1.md. [skip:ci, skip:test:long-running, skip:test:matrix-runner, skip:test:very-long-running] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Summary
yaml.dumpdefaultwidth=80wrapped long strings at column 80,causing some words to land at column 0 in
openapi_v1.yamlthe file invalid
into
API_REFERENCE_v1.md, breaking the rendered page on ReadTheDocsFix
width=float("inf")toyaml.dumpto disable line wrappingprint()instead ofconsole.print()to avoid Rich adding asecond layer of wrapping on top
Test plan
aignostics system openapi --output-format=yamlproduces valid YAML🤖 Generated with Claude Code