docs: show package tag instead of monorepo release in subpackage docs - #4229
docs: show package tag instead of monorepo release in subpackage docs#4229maxrjones wants to merge 4 commits into
Conversation
github-actions
Bot
added
the
needs release notes
|
this is awesome max! short term i'm leaning anti DRY (pro duplication) but longer term this is something our docs dep should handle without modifications. we should investigate upstreaming this fix |
thanks for the prompt feedback. I consolidated both the patch script and the mkdocs configuration files. |
| 1. Create a new project on [readthedocs.org](https://app.readthedocs.org) importing the `zarr-python` repository, named after the package (e.g. `zarr-metadata`). | ||
| 2. In the project's admin settings, set the configuration file path to `packages/<name>/.readthedocs.yaml`. That file also cancels pull request builds that don't touch the package. | ||
| 3. Add an automation rule matching the package's release tags (custom match `^zarr_<name>-v`, note the underscore) with the action "Activate version". Automation rules only apply to versions detected after the rule is created, so activate any earlier release tags manually from the versions list. | ||
| 4. When activating a version, edit its slug to the bare version number (`0.4.0`, not `v0.4.0`). RTD keeps a version record for every tag in the monorepo, including inactive ones not shown in the dashboard's versions list, and all of zarr-python's own release tags are `v`-prefixed — so a `v`-prefixed slug collides with zarr-python's release history ("A version with that slug already exists"), while bare version numbers cannot collide. |
There was a problem hiding this comment.
@d-v-b supposedly (according to Fable) this will address the issues discussed in #Zarr-Python > zarr-metadata docs. You're welcome to add me to RTD if you'd like any help with maintainence.
There was a problem hiding this comment.
I did add that automation rule, but didn't get the expected results! Happy adding you to rtd so you can tinker
| @@ -0,0 +1,698 @@ | |||
| version = 1 | |||
There was a problem hiding this comment.
I committed uv.lock since the lockfile is committed for zarr-metadata
| } | ||
|
|
||
| async function latestPackageTag() { | ||
| const response = await fetch( |
There was a problem hiding this comment.
this fires on every page load, and I think github has a rate limit on this endpoint, maybe we want to cache this internally?
| } | ||
|
|
||
| function patchCache(version) { | ||
| const facts = __md_get("__source", sessionStorage) |
There was a problem hiding this comment.
we probably need to watch this code carefully when / if we update material
There was a problem hiding this comment.
we probably won't be updating material 🫠 squidfunk/mkdocs-material#8523
2 participants
Summary
This PR patches mkdocs to use the subpackage's tag instead of Zarr-Python core's in the docs header.
For reviewers
Opinions on whether we should duplicate the patch on each sub-package (anti-DRY) or symlink (anti-windows).
Author attestation
TODO
docs/user-guide/*.mdchanges/