Skip to content

docs: restructure into per-interface guides, refresh branding, fix stale content [PYSDK-144] - #664

Merged
omid-aignostics merged 7 commits into
mainfrom
docs/PYSDK-144-restructure-guides-branding
Jun 2, 2026
Merged

docs: restructure into per-interface guides, refresh branding, fix stale content [PYSDK-144]#664
omid-aignostics merged 7 commits into
mainfrom
docs/PYSDK-144-restructure-guides-branding

Conversation

@omid-aignostics

@omid-aignosticsomid-aignostics commented May 31, 2026•
edited by atlassian Bot
Loading

Copy link
Copy Markdown
Collaborator

🛡️ Implements PYSDK-144 following CC-SOP-01 Change Control, part of our ISO 13485-certified QMS | Ketryx Project

Summary

  • Restructure the SDK docs into four self-contained "Get started" guides (Launchpad, CLI, Python Library, MCP) that share one account-signup partial via a MyST include (single source of truth).
  • Thin and reorder the Home/README to orient → decide → act; make "Next Steps" action-first; move the Platform Workflow overview + sequence diagram to the Platform Overview page; reword the intro to serve both the PyPI/GitHub README and the readthedocs "Platform Documentation" site.
  • Refresh branding: brand colours (light/dark), favicon, theme-adaptive Aignostics wordmark logo, footer version stamp; remove the announcement link bar.
  • Fix stale content (each verified against code): remove the no-op aignostics[qupath,marimo] command (the qupath extra is empty); fix dead client/utils.py reference (now platform/_utils.py); replace outdated run-state vocabulary with pending/processing/terminated + termination reasons; correct GUI button/menu labels; reference → external_id; document SDK metadata schema version v0.0.6.

Test plan

  • Strict Sphinx build (sphinx-build -W) passes with zero warnings; all four new pages and internal links/anchors render.
  • make docs reproduces the change with all committed files byte-identical.
  • CI green — note: the audit job fails on a pre-existing, unrelated uv advisory (GHSA-4gg8-gxpx-9rph, fix 0.11.15), tracked separately.

Scope

Documentation only — no src/, dependency, API, or behavioural changes. Generated reference artifacts (API_REFERENCE_v1.md, CLI_REFERENCE.md, openapi_v1.*, ATTRIBUTIONS.md) are excluded; they are make docs-driven and addressed separately.

Posted by Claude claude-opus-4-8 via Claude Code, applying skills cc-sop-01 on behalf of Omid Kokabi

@omid-aignostics@claude
docs: restructure into per-interface guides, refresh branding, fix st…
1a671bb
…ale content
Restructure
- Add a pathologist-focused "Get started with Launchpad" guide plus dedicated
CLI, Python Library, and MCP guides; all four share a single account-signup
partial via a MyST include (one source of truth).
- Thin and reorder the Home/README to orient -> decide -> act; make "Next Steps"
action-first (run your first analysis, starting with Launchpad). Move the
Platform Workflow overview + sequence diagram into the Platform Overview page.
- Lead the opening paragraph with the Platform while naming the Python SDK, so it
serves both the PyPI/GitHub README and the readthedocs "Platform Documentation".
Branding
- Aignostics brand colors (light/dark), favicon, theme-adaptive wordmark logo
(white on dark, aubergine on light), left-aligned brand, subordinate subtitle,
and a small footer version stamp. Remove the announcement link bar.
Stale-content fixes
- Drop the no-op aignostics[qupath,marimo] command (qupath extra is empty).
- Fix dead client/utils.py reference (now platform/_utils.py).
- Replace outdated run-state vocabulary with pending/processing/terminated +
termination reasons; correct button/menu labels; reference -> external_id.
- Bump documented SDK metadata schema version to v0.0.6.
Tailor install depth per audience and regenerate README.md from partials.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings May 31, 2026 20:03
@omid-aignosticsomid-aignostics added documentation Improvements or additions to documentation skip:test:long_running Skip long-running tests (≥5min) sop:cc-sop-01 CC-SOP-01 Change Control (feature / planned change) type:docs Documentation-only change labels May 31, 2026
@omid-aignosticsomid-aignostics self-assigned this May 31, 2026
CopilotAI reviewed May 31, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

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 restructures the SDK documentation into interface-specific getting-started guides, updates branding/theming for the Read the Docs site, and refreshes stale platform terminology and metadata references.

Changes:

  • Splits Launchpad, CLI, Python Library, and MCP onboarding into dedicated Sphinx pages backed by shared partials.
  • Simplifies the README/home page and moves the platform workflow overview into the platform section.
  • Updates documentation branding, footer version display, glossary terminology, and SDK metadata schema references.

Reviewed changes

Copilot reviewed 19 out of 27 changed files in this pull request and generated 8 comments.

Show a summary per file
FileDescription
README.mdRegenerated top-level README with streamlined interface selection and updated platform/glossary content.
docs/source/main.rstRemoves the old home include wrapper.
docs/source/index.rstIncludes the home partial directly and adds Get started/Reference toctrees.
docs/source/get_started_launchpad.rstAdds Sphinx wrapper for Launchpad guide.
docs/source/get_started_cli.rstAdds Sphinx wrapper for CLI guide.
docs/source/get_started_library.rstAdds Sphinx wrapper for Python Library guide.
docs/source/get_started_mcp.rstAdds Sphinx wrapper for MCP guide.
docs/source/conf.pyUpdates Furo branding options, favicon, and title.
docs/source/_templates/page.htmlAdds a custom footer template with version stamp.
docs/source/_static/custom.cssAdds sidebar brand and footer version styling.
docs/source/_static/aignostics-wordmark-light.svgAdds light-theme wordmark asset.
docs/source/_static/aignostics-wordmark-dark.svgAdds dark-theme wordmark asset.
docs/partials/README_main.mdReworks home/README content and next-step links.
docs/partials/README_platform.mdUpdates run state terminology and moves platform workflow content here.
docs/partials/README_glossary.mdUpdates Application Run and Reference glossary entries.
docs/partials/_get_started_signup.mdAdds shared account signup instructions.
docs/partials/get_started_launchpad.mdAdds Launchpad onboarding walkthrough.
docs/partials/get_started_cli.mdAdds CLI onboarding workflow.
docs/partials/get_started_library.mdAdds Python Library onboarding and examples.
docs/partials/get_started_mcp.mdAdds MCP server onboarding and configuration.
CLAUDE.mdUpdates SDK metadata run schema version references.

Comment threaddocs/partials/get_started_cli.md
Comment threaddocs/partials/get_started_mcp.md
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/README_main.md Outdated
@codecov

codecovBot commented May 31, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.
see 6 files with indirect coverage changes

@omid-aignostics
omid-aignostics marked this pull request as ready for review June 1, 2026 07:06
@omid-aignostics
omid-aignostics requested a review from a team as a code ownerJune 1, 2026 07:06
@omid-aignosticsomid-aignostics added skip:test:all Skip all test executions skip:codecov Skip Codecov reporting and check labels Jun 1, 2026
@omid-aignostics@claude
docs: use absolute Read the Docs URL for the Platform Overview link i…
c0cd1a2
…n README [PYSDK-144]
The README is generated from this partial and is also the PyPI long
description, where a relative platform_overview.md link 404s. Use the
absolute Read the Docs URL, matching the other links in the section.
Addresses Copilot review feedback on PR #664.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings June 1, 2026 07:21
CopilotAI reviewed Jun 1, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 19 out of 27 changed files in this pull request and generated 18 comments.

Comment threadREADME.md
Comment threadREADME.md Outdated
Comment threaddocs/partials/README_platform.md
Comment threaddocs/partials/README_platform.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
Comment threaddocs/partials/get_started_launchpad.md Outdated
omid-aignosticsand others added 2 commits June 1, 2026 10:09
@omid-aignostics@claude
docs: fix run-state wording in Platform Overview [PYSDK-144]
4710f94
Standardize on US spelling (canceled), align outputs-deletion wording
with the terminated state, and fix the 'provide enable' grammar.
Addresses Copilot review feedback on PR #664.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@omid-aignostics@claude
docs: use relative _static paths for Launchpad screenshots [PYSDK-144]
ce3d889
Switch the five screenshot references from /_static/... to _static/...
(both build identically to _images/..., verified); the relative form
is the conventional Sphinx style. Addresses Copilot review feedback.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
CopilotAI review requested due to automatic review settings June 1, 2026 09:37
CopilotAI reviewed Jun 1, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Pull request overview

Copilot reviewed 19 out of 27 changed files in this pull request and generated 8 comments.

Comment threadREADME.md Outdated
Comment threadREADME.md Outdated
Comment threaddocs/partials/README_platform.md Outdated
Comment threaddocs/partials/README_platform.md Outdated
Comment threadREADME.md Outdated
Comment threadREADME.md Outdated
Comment threaddocs/partials/README_platform.md Outdated
Comment threaddocs/partials/README_platform.md Outdated
@omid-aignostics@claude
docs: align interface count and spelling in Platform Overview [PYSDK-…
9bcb188
…144]
Update the workflow overview to 'multiple interfaces' enumerating all
four (Launchpad, CLI, Python Library, MCP server), and use US 'canceled'
in the cost paragraph for consistency with the API enum names.
Addresses Copilot review feedback on PR #664.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@omid-aignosticsomid-aignostics added the skip:ci Skip entire CI/CD pipeline label Jun 2, 2026
@omid-aignosticsomid-aignostics removed the skip:ci Skip entire CI/CD pipeline label Jun 2, 2026
@omid-aignosticsomid-aignostics added skip:test:e2e Skip end-to-end tests and removed skip:test:all Skip all test executions labels Jun 2, 2026
arne-aignx
arne-aignx approved these changes Jun 2, 2026
View reviewed changes

@arne-aignxarne-aignx left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved. Docs render correctly, can be merged after CI succeeded

@sonarqubecloud

sonarqubecloudBot commented Jun 2, 2026

Copy link
Copy Markdown

Quality Gate PassedQuality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@omid-aignostics
omid-aignostics merged commit 1c38faf into mainJun 2, 2026
77 of 79 checks passed
@omid-aignostics
omid-aignostics deleted the docs/PYSDK-144-restructure-guides-branding branch June 2, 2026 11:11
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@arne-aignxarne-aignxarne-aignx approved these changes

Assignees

@omid-aignosticsomid-aignostics

Labels

documentationImprovements or additions to documentationskip:codecovSkip Codecov reporting and checkskip:test:e2eSkip end-to-end testsskip:test:long_runningSkip long-running tests (≥5min)sop:cc-sop-01CC-SOP-01 Change Control (feature / planned change)type:docsDocumentation-only change

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@omid-aignostics@arne-aignx