Skip to content

fix(docs): fix broken API reference page on ReadTheDocs#453

Merged
omid-aignostics merged 4 commits intomainfrom
fix/docs-openapi-yaml-wrapping
Mar 2, 2026
Merged

fix(docs): fix broken API reference page on ReadTheDocs#453
omid-aignostics merged 4 commits intomainfrom
fix/docs-openapi-yaml-wrapping

Conversation

@omid-aignostics
Copy link
Copy Markdown
Collaborator

Summary

  • yaml.dump default width=80 wrapped long strings at column 80,
    causing some words to land at column 0 in openapi_v1.yaml
  • YAML parsers interpret bare words at column 0 as new keys, making
    the file invalid
  • Widdershins silently failed to parse it and output garbage markdown
    into API_REFERENCE_v1.md, breaking the rendered page on ReadTheDocs

Fix

  • Pass width=float("inf") to yaml.dump to disable line wrapping
  • Use print() instead of console.print() to avoid Rich adding a
    second layer of wrapping on top

Test plan

🤖 Generated with Claude Code

omid-aignostics and others added 3 commits February 27, 2026 17:51
…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>
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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=yaml to emit unwrapped YAML to stdout.
  • Regenerate docs/source/_static/openapi_v1.yaml and API_REFERENCE_v1.md from 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.

Comment thread README.md
Comment thread API_REFERENCE_v1.md Outdated
…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>
@omid-aignostics omid-aignostics merged commit 945fb12 into main Mar 2, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants