Skip to content

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

Open
omid-aignostics wants to merge 4 commits intomainfrom
fix/docs-openapi-yaml-wrapping
Open

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

Conversation

@omid-aignostics
Copy link
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

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 on lines +226 to +234
### 🤖 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> |

Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
Comment on lines 1 to 5
<!-- 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.
Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

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

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.

Copilot uses AI. Check for mistakes.
…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>
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