Repository navigation
docs: build the docs with MkDocs on Read the Docs - #81
Merged
Merged
Conversation
Turn the loose docs and the long README into a MkDocs Material site for Read the Docs, structured as in cloud-registry-ui: - user guide (new overview, plus the workflow examples); - operator guide: deployment (moved), configuration (the README's settings and privacy notice), upgrading, compatibility; - development: setup, checks, tests and docs build (from the README), and releasing (moved, release notes go into nav). The README keeps the synopsis, deployments, a quick start, citation, contributing, contact and licence, and links to the docs with a docs badge. References to the moved files in workflow comments, the smoke test script and the Dockerfile follow the move; the releasing guide now links the org's contributing guide in elixir-cloud-aai/.github. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add the job `docs` ("Docs"), as in cloud-registry-ui: it builds the
MkDocs site with Python 3.13, as Read the Docs does, in strict mode, so
that broken links and anchors or pages missing from nav fail CI. The
gate and `publish` need it. The release-notes check stays in
`readiness`.
Closes #73
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Releasing: indent the steps by 4 spaces and separate them, so that MkDocs renders them as one list; show the nav entry for the notes. - Deployment: new intro, sentence-case headings, the login provider and service requirements once (scopes, token type, allowlisting), and the settings only in Configuration. - User guide: TES services are listed without login, too. - Configuration and README quick start: no quotes in env files for docker run --env-file; the quick start links the releases. - Dependabot: update the docs packages (pip, /docs) monthly. - Reflow comments after the path changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Move the note on which settings reach the browser and the behaviour of the privacy settings from the deployment page to Configuration, and use sentence case for the security recommendations. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Reviewer's GuideConfigurationConfigure Read the Docs and pin MkDocs dependencies, add monthly Dependabot updates, and require a strict documentation build in CI before the gate and image publishing can pass.
DocumentationRead the new documentation structure and its home page, then review the user guide and moved workflow examples together.
Review the operator guidance as a set: the reorganized deployment page, its dedicated configuration and upgrade pages, and the compatibility overview.
Review the development guide and its moved release instructions together, including the added release-note navigation guidance.
Review the README as the concise project entry point, quick start, and link hub for the new guides.
Other changesFiles not grouped.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #81 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 12 12
Lines 273 273
Branches 77 77
=========================================
Hits 273 273 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
uniqueg
marked this pull request as ready for review
November 14, 2026 22:09
Linked issuesChecked at commit eb8bf33 #73 docs: build the docs with MkDocs on Read the Docs · 6 of 7 met
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 6 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="docs/development/releasing.md" line_range="116-118" />
<code_context>
+ the version.
+
+ ```bash
+ git push origin "${sha}:main" && # fails unless it is a fast-forward
+ git tag -s "v${version}" "${sha}" -m "v${version}" &&
+ git push origin "v${version}"
+ ```
+
</code_context>
<issue_to_address>
**Main advances without a release tag**
When the main push succeeds but local tag signing or the remote tag push fails, `git push origin "${sha}:main"` has already advanced `main`, so a later failure in `git tag -s` or `git push origin "v${version}"` leaves `main` pointing to an untagged commit; a hosting project that follows `main` can deploy it before the release exists.
Create the signed tag before pushing, then atomically push both `main` and the tag, or provide recovery instructions for restoring the invariant after a partial failure.
</issue_to_address>
### Comment 2
<location path="README.md" line_range="24" />
<code_context>
-and follow their runs. The rest of this README describes how to run Krini
-locally and how to contribute; see the [Deployment Guide](docs/deployment.md)
-for deployments.
+and follow their runs. Krini is generic: deploy it with its container image
+for your own registry, login provider and services.
+
</code_context>
<issue_to_address>
**Custom providers cannot authenticate**
When an operator configures an OIDC provider whose endpoints are not at `/oidc/authorize`, `/oidc/token`, and `/oidc/userinfo`, the login flow constructs those paths from `LS_LOGIN_URL` instead of using the provider’s endpoint paths, so authentication fails despite the generic-provider claim.
Use the provider’s discovered or configured endpoint paths instead of hard-coding these routes.
Also at `README.md:25`.
</issue_to_address>
### Comment 3
<location path="docs/user-guide/index.md" line_range="19-20" />
<code_context>
+## Logging in
+
+Use **Login** to log in with the login provider of the deployment, such as
+LS Login. Krini then sends your access token to the services you use, so
+that they know who you are; services that require login accept it only if
+they trust the deployment's client (see the
+[Operator guide](../operator-guide/deployment.md#service-configuration)).
</code_context>
<issue_to_address>
**TES token requirements are misleading**
When users follow the login description or operators configure services according to the deployment guide, `ECCClientGa4ghTesCreateRuns` passes only the TES URL, while the WES provider adds the bearer token; operators therefore get incorrect guidance to configure TES JWT-token support and users are told TES receives their identity token when it does not.
Clarify that Krini currently sends access tokens only to WES, and scope the JWT and allowlisting requirements to WES until TES requests include a token.
Also at `docs/operator-guide/index.md:9`.
</issue_to_address>
### Comment 4
<location path="docs/operator-guide/configuration.md" line_range="31" />
<code_context>
-APP_ORIGIN=http://localhost:3000
-
-# Privacy notice (optional)
-PRIVACY_CONTROLLER="Example Institute, Example Street 1, Example City"
-PRIVACY_CONTACT=privacy@example.org
-PRIVACY_NOTICE_URL=https://example.org/privacy
</code_context>
<issue_to_address>
**Privacy controller shows quotes**
When an operator copies the displayed `PRIVACY_CONTROLLER` example into a Docker `--env-file`, `textOf` and `privacySettings` trim whitespace but preserve the quote characters, and the privacy page renders the value verbatim, so visitors see quotation marks around the controller name.
Remove the surrounding quotes from the Docker env-file example.
</issue_to_address>
### Comment 5
<location path="docs/development/releasing.md" line_range="34" />
<code_context>
+ end of `nav`; later ones add their notes at its top:
+
+ ```yaml
+ - Releases:
+ - "0.2.0": releases/0.2.0.md
+ - "0.1.0": releases/0.1.0.md
</code_context>
<issue_to_address>
**Release section nests under Development**
When maintainers follow the displayed nav snippet literally, maintainers who follow this snippet append `Releases` as a child of `Development`, rather than as a top-level section, so the release notes appear in the wrong place in the site navigation.
Indent `- Releases:` to the same level as the other top-level nav sections.
</issue_to_address>
### Comment 6
<location path="mkdocs.yml" line_range="18" />
<code_context>
+
+theme:
+ name: material
+ logo: images/logo_elixir_on_cloud_night.png
+ features:
+ - content.code.copy
</code_context>
<issue_to_address>
**Header logo image is missing**
The configured logo path resolves to `docs/images/logo_elixir_on_cloud_night.png`, but no image files were found under `docs/`; the generated site therefore displays a broken logo in its header.
Add the referenced logo image under `docs/images/` or point the theme setting at an image that exists.
</issue_to_address>Sourcery assessment
Approval pending. 4 findings to address first.
Blocking findings: docs/development/releasing.md:118, README.md:24, docs/user-guide/index.md:20, docs/operator-guide/configuration.md:31
- Releasing: sign the tag first, then push it and main in one atomic push, so that a failure can't leave main moved but untagged. - README and home page: login is with LS Login for now; other OIDC providers are planned (#43). - User guide and deployment: Krini sends tokens only to WES services so far (#44); the service requirements apply to TES once it does. - Configuration: the example has no quotes, for docker --env-file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This branch had an error being deployed
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.
Summary
Turns Krini's docs into a MkDocs Material site for Read the Docs, structured as in cloud-registry-ui, and builds it strictly in CI.
mkdocs.yml(Material,validationwarnings,site_urlfromREADTHEDOCS_CANONICAL_URL),.readthedocs.yaml(fail_on_warning: true),docs/requirements.txt(pinned), and a Dependabotpipentry for/docs.docs/deployment.md, deduplicated, sentence-case headings); configuration (the README's settings, privacy notice and env-file notes); upgrading.docs/releasing.md). It now says how release notes go intonav, its steps render as one list, and it links the org's contributing guide inelixir-cloud-aai/.githubinstead of the retired repo.docs("Docs"):mkdocs build --strictwith Python 3.13, as on Read the Docs, needed by the gateCI passedand bypublish. The release-notes format check stays inRelease readiness, which covers more cases (date, TODOs, tagged versions) than cloud-registry-ui's docs-job check.docsadditionally fails if the notes aren't innav.ci.yml,release.yml,scripts/check-image.shand theDockerfilefollow the moves (comments only).Nothing from the old README or
docs/is lost; the reviewers checked this explicitly.Closes #73
Verification
mkdocs build --strict(mkdocs 1.6.1, mkdocs-material 9.8.0, Python 3.13): passes. Before the content existed it failed on thenaventries and broken links, as intended.development/releasing/index.htmlhas one ordered list with 4 steps (round-1 review found it rendered as 1).docs/releases/0.1.0.md: it fails without anaventry and passes with the documented snippet.actionlint1.7.12 with shellcheck 0.11.0 on all workflows: no findings.adversarial-reviewerandquality-reviewer, 2 rounds. All confirmed findings are fixed: list rendering, a wrong statement about TES listing, docs duplication, Dependabot for the docs packages, comment wrapping, and quotes in env files.CI passed. Every job passed, including the newDocsjob (20 s), and so did Codecov. The non-required external checkVercel – krinifrom the old org Vercel project fails, as on other PRs. That's unrelated: Krini deploys on Rahti.Maintainer to-do (not a blocker for the merge)
krini, default branchdev, PR builds on), right after the merge. Until then the README's docs badge and links return 404. Step 6 of the UI steps file has the details.Declined review findings
ci.ymland.readthedocs.yaml, as in cloud-registry-ui. Each comment points at the other. Not centralised.Open questions
None.
🤖 Generated with Claude Code
Summary by Sourcery
Build and validate a structured MkDocs documentation site on Read the Docs while consolidating project guidance and simplifying the README.
New Features:
Bug Fixes:
Enhancements:
Build:
CI:
Documentation:
Chores: