docs: remove README alpha note and run make docs#521
Conversation
olivermeyer
requested a review
from helmut-hoffer-von-ankershoffen
as a code owner
|
There was a problem hiding this comment.
Pull request overview
Updates repository documentation output after removing the README “alpha” note, including regenerated CLI and API reference artifacts (OpenAPI v1 now reflecting API v1.4.0).
Changes:
- Removed the “alpha / early access” NOTE block from the README header content.
- Regenerated OpenAPI v1 artifacts (YAML/JSON) and the rendered API v1 reference, including new scheduling fields and a new artifact file download endpoint.
- Regenerated CLI reference docs (including a new
--for-organizationoption and updated examples).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Removes the alpha NOTE block from the generated README header. |
| docs/partials/README_header.md | Removes the alpha NOTE block from the README header partial used for generation. |
| docs/source/_static/openapi_v1.yaml | Updates OpenAPI v1 spec to v1.4.0, adds scheduling fields and artifact file endpoint, and various schema tweaks. |
| docs/source/_static/openapi_v1.json | JSON form of the updated OpenAPI v1 spec (mirrors YAML changes). |
| API_REFERENCE_v1.md | Regenerated API v1 reference documentation based on the updated OpenAPI spec. |
| CLI_REFERENCE.md | Regenerated CLI reference documentation (new options and updated examples). |
| get: | ||
| description: 'Download the artifact file with the specified artifact_id, belonging to the specified run. | ||
|
|
||
| The artifact_is is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also |
There was a problem hiding this comment.
In the new endpoint description, artifact_is looks like a typo and makes the sentence confusing. Please change it to artifact_id (and consider rephrasing to “The artifact_id is returned by …”).
| The artifact_is is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also | |
| The `artifact_id` is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also |
| content: | ||
| application/json: | ||
| schema: {} | ||
| description: Successful Response |
There was a problem hiding this comment.
The GET /v1/runs/{run_id}/artifacts/{artifact_id}/file endpoint is described as a file download / possible redirect, but the 200 response is declared as application/json with an empty schema. This causes the generated docs to show null/JSON parsing, which is inconsistent. Please model 200 as a binary payload (e.g., application/octet-stream with format: binary) and/or document the redirect-only behavior and remove/adjust the JSON response body.
| content: | |
| application/json: | |
| schema: {} | |
| description: Successful Response | |
| description: Artifact file content | |
| content: | |
| application/octet-stream: | |
| schema: | |
| type: string | |
| format: binary |
| "Public" | ||
| ], | ||
| "summary": "Get Artifact Url", | ||
| "description": "Download the artifact file with the specified artifact_id, belonging to the specified run.\nThe artifact_is is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also\nbe retrieved via `GET /v1/runs/{run_id}/items/{external_id}`.\n\nThe endpoint may return a redirect response with a presigned URL to download the artifact file from the storage\nbucket. The presigned URL is valid for a limited time, so it should be used immediately after receiving the response.", |
There was a problem hiding this comment.
The new endpoint description includes artifact_is, which appears to be a typo (should be artifact_id). This is also user-facing in generated docs.
| "description": "Download the artifact file with the specified artifact_id, belonging to the specified run.\nThe artifact_is is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also\nbe retrieved via `GET /v1/runs/{run_id}/items/{external_id}`.\n\nThe endpoint may return a redirect response with a presigned URL to download the artifact file from the storage\nbucket. The presigned URL is valid for a limited time, so it should be used immediately after receiving the response.", | |
| "description": "Download the artifact file with the specified artifact_id, belonging to the specified run.\nThe artifact_id is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also\nbe retrieved via `GET /v1/runs/{run_id}/items/{external_id}`.\n\nThe endpoint may return a redirect response with a presigned URL to download the artifact file from the storage\nbucket. The presigned URL is valid for a limited time, so it should be used immediately after receiving the response.", |
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": {} |
There was a problem hiding this comment.
For GET /v1/runs/{run_id}/artifacts/{artifact_id}/file, the 200 response is specified as application/json with {} schema, but the description says it downloads a file and may return a redirect. This leads to incorrect generated examples (JSON null) and client guidance. Please represent the 200 response as a binary download content-type (or remove 200 if it always redirects), and align the docs accordingly.
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": {} | |
| "description": "Artifact file content", | |
| "content": { | |
| "application/octet-stream": { | |
| "schema": { | |
| "type": "string", | |
| "format": "binary" | |
| } |
| * `--qupath-project / --no-qupath-project`: Create a QuPath project referencing input slides and results. | ||
| The QuPath project will be created in a subfolder of the destination directory. | ||
| This option requires the QuPath extension for Launchpad: start the Launchpad with `uvx --with "aignostics" aignostics ...` |
There was a problem hiding this comment.
These lines have trailing whitespace at the end of the line, which is easy to miss in diffs and can create inconsistent Markdown rendering/formatting. Please remove the trailing spaces.
| * `--qupath-project / --no-qupath-project`: Create a QuPath project referencing input slides and results. | |
| The QuPath project will be created in a subfolder of the destination directory. | |
| This option requires the QuPath extension for Launchpad: start the Launchpad with `uvx --with "aignostics" aignostics ...` | |
| * `--qupath-project / --no-qupath-project`: Create a QuPath project referencing input slides and results. | |
| The QuPath project will be created in a subfolder of the destination directory. | |
| This option requires the QuPath extension for Launchpad: start the Launchpad with `uvx --with "aignostics" aignostics ...` |
| ```python | ||
| import requests | ||
| headers = { | ||
| 'Accept': 'application/json', | ||
| 'Authorization': 'Bearer {access-token}' | ||
| } | ||
|
|
||
| r = requests.get('/api/v1/runs/{run_id}/artifacts/{artifact_id}/file', headers = headers) | ||
|
|
||
| print(r.json()) | ||
|
|
There was a problem hiding this comment.
The code samples for this endpoint set Accept: application/json and parse the response as JSON (r.json() / res.json()), but the endpoint is described as a file download and may return a 307 redirect. Please update the samples to handle redirects and download the file bytes/stream (and adjust the Accept header accordingly).
| *Get Artifact Url* | ||
|
|
||
| Download the artifact file with the specified artifact_id, belonging to the specified run. | ||
| The artifact_is is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also |
There was a problem hiding this comment.
Typo in the endpoint description: artifact_is should be artifact_id.
| The artifact_is is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also | |
| The artifact_id is returned by the `GET /v1/runs/{run_id}/items` endpoint as part of the item results, and can also |
🔍 PR Review - Documentation Update✅ Summary: APPROVED - Ready to MergeThis is a clean documentation-only PR that removes the alpha notice from README and regenerates documentation artifacts via ✅ Critical Checks - All Passed1. Test Markers ✅# Verified: All 785 tests have proper markers (unit/integration/e2e)
$ uv run pytest -m "not unit and not integration and not e2e" --collect-only
================= no tests collected (785 deselected) in 8.47s =================Result: No unmarked tests found. ✅ 2. Code Quality ✅$ make lint
nox > ruff check .
All checks passed!
nox > ruff format --check .
165 files already formatted
nox > pyright --pythonversion 3.14.3 --threads
0 errors, 0 warnings, 0 informations
nox > mypy src
Success: no issues found in 81 source filesResult: All linting checks pass (ruff, pyright, mypy). ✅ 3. Test Coverage ✅Result: No code changes, so coverage is unaffected. ✅ 4. Conventional Commits ✅Result: Proper conventional commit format with 📋 Changes SummaryFiles Modified (6 total, 0 Python files):
🔎 Detailed AnalysisArchitecture Compliance ✅
Breaking Changes ✅
Security & Medical Device Compliance ✅
CI/CD Impact ✅
Documentation Quality ✅The documentation updates are legitimate artifacts from running
🎯 Verification CommandsI executed these commands to verify the PR: # 1. Check out PR branch
git checkout pr-521
# 2. Verify no Python code changes
git diff origin/main..HEAD --name-only
# Result: Only .md and .json/.yaml documentation files
# 3. Run linting
make lint
# Result: All checks passed (ruff, pyright, mypy)
# 4. Check test markers
uv run pytest -m "not unit and not integration and not e2e" --collect-only
# Result: 0 tests collected (all 785 tests properly marked)
# 5. Verify commit message
git log --format="%s" origin/main..HEAD
# Result: "docs: remove README alpha note and run make docs"📝 RecommendationsFor Merging:
For Follow-up (Optional):
🎉 PraiseExcellent work on this PR:
🏁 Final VerdictStatus: ✅ APPROVED - READY TO MERGE Blocking Issues: None Review performed by Claude Code following CLAUDE.md and .github/CLAUDE.md standards for medical device software. |
Codecov Report✅ All modified and coverable lines are covered by tests. |
No description provided.