docs: add v2 migration guide and dual-package install instructions [PYSDK-142]#652
Open
ari-nz wants to merge 3 commits into
Open
docs: add v2 migration guide and dual-package install instructions [PYSDK-142]#652ari-nz wants to merge 3 commits into
ari-nz wants to merge 3 commits into
Conversation
Adds documentation for the v2 dual-package distribution that splits the SDK into aignostics-sdk (slim API client) and aignostics (full SDK), including migration guide for users upgrading from v1.
There was a problem hiding this comment.
Pull request overview
Adds documentation for a proposed/announced v2 split of the SDK into a slim aignostics-sdk distribution (new aignostics_sdk.* namespace) plus a migration guide, and updates the docs build pipeline to prepend a static aignostics-sdk CLI section to the generated CLI reference.
Changes:
- Add a new Sphinx migration page (
docs/source/migration.md) and link it into the docs nav. - Update README partials to describe dual-package installation and include migration highlights + links.
- Extend
noxfile.pyCLI reference generation to prepend a staticaignostics-sdkCLI header partial before the typer-generatedaignosticsCLI docs.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
src/aignostics/CLAUDE.md |
Adds a v2 architecture note about module/package relocation. |
packages/aignostics-sdk/CLAUDE.md |
Introduces documentation for a new slim distribution layout and CLI entry point. |
noxfile.py |
Changes CLI reference generation to stitch a static header + typer output. |
docs/source/migration.md |
New v2 migration guide page (imports/installation/CLI changes). |
docs/source/index.rst |
Adds migration to the Sphinx toctree. |
docs/partials/README_main.md |
Adds dual-package install guidance + a migration section/link. |
docs/partials/README_footer.md |
Adds a “Further Reading” link to the migration guide. |
docs/partials/CLI_REFERENCE_header.md |
New static aignostics-sdk CLI reference header to prepend to generated docs. |
Comment on lines
+3
to
+8
| > **v2 Architecture Note**: In v2, this `src/aignostics/` tree contains only the *heavy* modules: | ||
| > `application`, `wsi`, `dataset`, `bucket`, `qupath`, `notebook`, `gui`, and `system`. | ||
| > The `platform` and `utils` modules (plus `constants`) have moved to the slim package at | ||
| > `packages/aignostics-sdk/` under the `aignostics_sdk` namespace. | ||
| > The full `aignostics` package depends on `aignostics-sdk` and re-exports nothing from those | ||
| > moved modules — callers must update their imports (see `migration.md` in the docs). |
Comment on lines
+1
to
+6
| # CLAUDE.md - aignostics-sdk (Slim Package) | ||
|
|
||
| This is the **slim distribution** of the Aignostics SDK, published to PyPI as `aignostics-sdk`. | ||
| It contains only the platform API client and core utilities — no WSI processing, no GUI, no dataset | ||
| downloads, no cloud storage abstraction. | ||
|
|
Comment on lines
+3
to
+7
| v2 of the Aignostics Python SDK introduces `aignostics-sdk`, a slim distribution that contains | ||
| only the platform API client and core utilities. The full `aignostics` package now depends on | ||
| `aignostics-sdk` and delegates platform/utils functionality to it. | ||
|
|
||
| This is a **breaking change** for anyone importing `aignostics.platform` or `aignostics.utils` |
Comment on lines
+27
to
+30
| > **v2 dual-package distribution**: The SDK is now published as two separate PyPI packages. | ||
| > Use `aignostics-sdk` for the slim API client, or `aignostics` for the full SDK with GUI, WSI | ||
| > processing, and dataset downloads. See the [v2 Migration Guide](#migrating-from-v1-to-v2) | ||
| > if you are upgrading from v1. |
Comment on lines
+119
to
+122
| **Options**: | ||
|
|
||
| * `--pretty / --no-pretty`: Pretty-print the JSON output. [default: no-pretty] | ||
| * `--help`: Show this message and exit. |
Comment on lines
+134
to
+137
| **Options**: | ||
|
|
||
| * `--pretty / --no-pretty`: Pretty-print the JSON output. [default: no-pretty] | ||
| * `--help`: Show this message and exit. |
This was referenced May 28, 2026
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.
Release Train — PYSDK-133
Summary
docs/partials/README_main.md: Added dual-package installation section near the top of Installation (slimaignostics-sdkvs fullaignostics), plus a v2 Migration Guide section with import table, CLI changes, and API client-only install instructions.docs/partials/README_footer.md: Added link to migration guide in Further Reading.docs/partials/CLI_REFERENCE_header.md(new): Static partial documenting theaignostics-sdkslim CLI entry point (user login/logout/whoami,sdk run-metadata-schema,sdk item-metadata-schema).noxfile.py: Updated_generate_cli_reference()to prependCLI_REFERENCE_header.mdto the typer-generatedaignosticsCLI docs when buildingCLI_REFERENCE.md.docs/source/migration.md(new): Full v2 migration guide as a Sphinx page — import path table, installation changes, CLI changes, health check pattern, and quick checklist.docs/source/index.rst: Addedmigrationto the toctree so the migration page appears in rendered docs.src/aignostics/CLAUDE.md: Added v2 architecture note at top explaining thatplatform,utils, andconstantshave moved topackages/aignostics-sdk/under theaignostics_sdknamespace.packages/aignostics-sdk/CLAUDE.md(new): CLAUDE.md for the new slim package — what it contains, Python namespace, CLI entry point, source history, dependencies, and module architecture.Test plan
make lintpasses (pre-push hook confirmed all checks green)make docsbuilds without errors (migration.md is syntactically valid MyST; myst_parser is enabled in conf.py)