sopel icon indicating copy to clipboard operation
sopel copied to clipboard

docs: add warning when rendering preview docs

Open SnoopJ opened this issue 1 year ago • 1 comments

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

  • [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 (runs make lint and make test)
  • [x] I have tested the functionality of the things this change touches

SnoopJ avatar Nov 12 '23 01:11 SnoopJ

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.

SnoopJ avatar Nov 13 '23 21:11 SnoopJ