sopel
sopel copied to clipboard
docs: add warning when rendering preview docs
Description
I had not realized that the unstable documentation was being regularly built against master
, and I thought it would be helpful if these preview docs included a warning about their preview-ness as well as a reference to the specific commit they were built against.
The warning added by this changeset is included on all pages using Sphinx's rst_prolog
variable, but only rendered when the Sopel version is a pre-release (i.e. .devN
) version.
Below is an example of how preview documentation renders (the links points to the relevant commit on GitHub and https://sopel.chat/docs/, respectively)
And here's what the docs look like for a release version:
Checklist
- [x] I have read CONTRIBUTING.md
- [x] I can and do license this contribution under the EFLv2
- [x] No issues are reported by
make qa
(runsmake lint
andmake test
) - [x] I have tested the functionality of the things this change touches
using subprocess in Python is something I'm very averse to for many reasons.
Is that a generalized aesthetic concern, or are you thinking of specific failure modes here?
An alternative that occurred to me while putting this PR together would be to add a Makefile
target for the preview documentation that retrieves the relevant commit information and passes it to Sphinx. I don't know what the specific mechanism would be, but I'm sure we could pass it in.
Edit: per discussion on IRC, I will rewrite to shove as much git
wrangling into the Makefile
as possible, without error handling if git
is not present or if calling git
fails.