docs build workflow #36
Conversation
|
May be blocked until sphinx rtd theme 3.0.0 is released per this issue: readthedocs/sphinx_rtd_theme#1598 Edit: Found a work around, but we should update the dependency once 3.0.0 is officially released |
| run: | | ||
| source .venv/bin/activate | ||
| which sphinx-build | ||
| make build-docs |
There was a problem hiding this comment.
Does this edit the doc files? Do you need to commit and push this somehow? This discussion has an example workflow where they commit and push the changes induced by a script.
There was a problem hiding this comment.
So I'm intentionally not pushing the built html docs to the Repo. My thinking is that it could add a lot of noise of extra changes as the html files come in, and could potentially make small changes look much bigger than they are, since they're effectively a build artifact rather than source code if that makes sense. Do you have a strong opinion on including the built html files?
There was a problem hiding this comment.
If the html files are not added to the repo, where are they added to? How do we edit the docs if we want to add notes that can't be immediately deduced from the source code?
There was a problem hiding this comment.
I think maybe I'm just somewhat confused by what this workflow captures. Does it just convert the markdown files in docs/ to documentation on github pages? Why does this step run if the head_ref is not dev?
There was a problem hiding this comment.
So this runs always to make sure that any changes don't cause the documentation build to break. However, we only push the changes to a separate gh-pages branch when it is dev that is changing.
There was a problem hiding this comment.
The deployment though is based off the strategy here: https://github.com/KempnerInstitute/kempner-hpc-handbook/blob/main/.github/workflows/deploy_action.yml
There was a problem hiding this comment.
Do we care if the documentation build breaks if it is a PR to something that is not dev or main? I'll approve since this isn't something I'd block on, but I often build multiple PRs chaining on each other to make it clear what steps are involved in a big change, and I wouldn't expect docs to be built on prematurely.
There was a problem hiding this comment.
Ah, I see what you're saying, I can update this so it runs on pushes to dev/PRs to dev only
There was a problem hiding this comment.
got it set up to only run on PRs to dev
* docs build workflow * use https git repo for sphinxrtd * use release archive for rtd theme * explicitly use sphinx make * activate venv before building docs * fix build output dir * only run on PRs/pushes to dev
closes #33
Builds docs on push to all non-main branches
On
dev, pushes built docs to github pages