sopel-irc / sopel

:robot::speech_balloon: An easy-to-use and highly extensible IRC Bot framework. Formerly Willie.
https://sopel.chat
Other
951 stars 405 forks source link

docs: add warning when rendering preview docs #2559

Open SnoopJ opened 7 months ago

SnoopJ commented 7 months ago

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)

image

And here's what the docs look like for a release version:

image

Checklist

SnoopJ commented 7 months ago

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.