Missing version and release in generated docs

[warsaw]

Sphinx supports configuration variables version and release. I set these in my conf.py file but they do not appear to be rendered into the page in the furo theme. I tried to grep the theme source but couldn't find this anywhere, whereas I do see where copyright is rendered. I can of course sneak this into my copyright but it doesn't look fantastic. I think I could modify page.html but that's a lot of work to support a standard Sphinx setting.

Am I missing something?

[pradyunsg]

These variables can be included in your regular documentation prose using the substitutions that Sphinx provides |version| and |release|.

Where do you expect to be able to see this version information on a Furo documentation page? It is possible to use an f-string to include it in the html_title, which is the only reasonable place I could come up with.

[warsaw]

I'll play with that, but where I was thinking about it was in the page footer, as seen on the Mailman documentation. That's not generated by Furo theme, but you can see how the footer includes the git sha at the bottom:

[warsaw]

I can kind of do this with rst_epilog but I'd much rather it show in the footer below the horizontal line, i.e. on the same line as the Copyright.

[pradyunsg]

I'm looking into this today. :)

[pradyunsg]

That git revision hash comes from the Read the Docs theme's tight integration with the things that Read the Docs does: https://github.com/readthedocs/sphinx_rtd_theme/blob/d64dadf1ceec4f9ff6c1ca2d3ea4c3d0fdb0e8d2/sphinx_rtd_theme/footer.html#L33

I'm not sure I want to include that level of integration with RTD. I'll give it some thought about what extent I want to expose stuff that RTD provides to themes.

[marxin]

Just wanted to mention, that I would welcome the support of revision in the Furo theme footer.

[warsaw]

I see this was closed yesterday @pradyunsg but I don't see a resolution in the comments. Did you just decide not to fix this?

[pradyunsg]

Hmm... I think I accidentally closed this while bulk-processing a bunch of long-standing-but-unmoved discussions. 😅

Reopened it.

[pradyunsg]

Hmm... I'm leaning towards letting end users inject their own chunk of raw Jinja2 template stuff, into the footer. That would enable folks to inject their own Jinja content that is tightly coupled with how RTD does things if that's what they want.

Based on some discussions with the RTD folks at PyCon, they seem to want to move in the direction of reducing coupling with the Sphinx build and doing things more on the transport/page-serve time (eg: building out https://github.com/readthedocs/addons, and unblocking more non-Sphinx usage) and want to discourage use of RTD-isms at build time overall, so doing this by default feels a bit out of line with that.

[warsaw]

Interesting! I'll have to investigate, but that does sound like a reasonable way forward. Thanks for reopening this issue.