fix(docs): fix broken API reference page on ReadTheDocs#453
Merged
omid-aignostics merged 4 commits intomainfrom Mar 2, 2026
Merged
fix(docs): fix broken API reference page on ReadTheDocs#453omid-aignostics merged 4 commits intomainfrom
omid-aignostics merged 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. |
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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