ci: add automated doc checks (and related starter pack updates)#2099
Conversation
| # The docs have a lot of external links, so the link checker takes a long time to run. | ||
| # As of Oct 2025, the link checker fails on many Read the Docs links because RTD's | ||
| # servers respond with 429 (Too Many Requests) without allowing retry after delay. | ||
| # Given this, it's best to run the workflow manually and inspect the results. |
There was a problem hiding this comment.
I believe we're talking to RTD about this
|
|
||
| * the specified location based on the storage section of `charmcraft.yaml`, or | ||
| * the default location `/var/lib/juju/storage/<storage-name>/<num>`, where num is zero for 'normal'/singular storages or an integer ID for storages that support multiple attachments. | ||
| * the default location `/var/lib/juju/storage/<storage-name>/<num>`, where `<num>` is zero for 'normal'/singular storages or an integer ID for storages that support multiple attachments. |
There was a problem hiding this comment.
Minor doc change to avoid adding a spelling exception for "num"
| @test -d $(VENVDIR) || uv venv --python 3.11 $(VENVDIR) | ||
| uv pip install --directory $(VENVDIR) --requirements ../../requirements.txt | ||
| uv pip install --directory $(VENVDIR) "ops[testing,tracing] @ ../../.." | ||
| uv pip install --directory $(VENVDIR) rst2html vale |
There was a problem hiding this comment.
These dependencies are required by the spellchecker. I suppose we could add them to requirements.txt, but then that file would no longer match the starter pack. This part of the Makefile already doesn't match the starter pack
There was a problem hiding this comment.
I'm curious why the starter pack doesn't include the spellchecker requirements?
There was a problem hiding this comment.
It does, but it hardcodes them in the Makefile. Actually, now I think about it, why aren't they listed in requirements.txt instead...? I'll investigate that before finishing this PR
There was a problem hiding this comment.
I'm updating the starter pack to put the dependencies in requirements.txt (#456). I've preemptively included the same changes here.
| @@ -0,0 +1,269 @@ | |||
| #! /usr/bin/env python | |||
There was a problem hiding this comment.
File added from the starter pack, unchanged
| @@ -0,0 +1,151 @@ | |||
| #! /usr/bin/env python | |||
There was a problem hiding this comment.
File added from the starter pack, unchanged except for cleaning up whitespace (which I'm fixing in the starter pack: #448)
dwilding
changed the title
james-garner-canonical
left a comment
james-garner-canonical
left a comment
There was a problem hiding this comment.
LGTM. The separation of the workflows makes sense to me. I guess we weren't running the docs workflows in CI in ops previously, since these are new workflows.
|
Thanks!
Yes, that's right |
dimaqq
left a comment
dimaqq
left a comment
There was a problem hiding this comment.
Aside: could the code and base settings be a github action (or a PYPI package) that can be reused by different projects, rather than everyone copying the same source into their repos?
(obv., that's a question for another day)
3 participants
This PR does a few things related to the documentation starter pack:
Makes sure that the spell checker can be run with
make -C docs spelling, makes sure that the spell checker passes, and adds a workflow to run the spell checker on PRs & pushes.Configures the link checker with URLs that are known to fail, and adds a manual workflow to run the link checker. Manual for now because the link checker takes a long time and produces unexpected errors (see my comments for more detail).
Adds the update script from the starter pack.