search

python / cpython

The Python programming language
https://www.python.org
Other
62.7k stars 30.06k forks source link

docs: New sphinx substitution #115531

Open smontanaro opened 7 months ago

smontanaro commented 7 months ago

Documentation

(A clear and concise description of the issue.)

smontanaro commented 7 months ago

(Sorry about the premature issue creation. Not sure what "hot" key I hit...)

I believe there was a new placeholder variable added recently ("version" perhaps?) what was meant to ease the insertion of specific version strings at release time. I just noticed mention of a few variables in the reStructured Text quick reference. Does mention of this new item belong there?

Just close if I'm off-base.

hugovk commented 7 months ago

Yes, they're called "substitutions".

Sphinx provides some defaults like |version| and |release|, as you noted in the devguide link.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#default-substitutions

And we recently added these:

https://github.com/python/cpython/blob/ae460d450ab854ca66d509ef6971cfe1b6312405/Doc/conf.py#L67-L71

We could document these in the devguide too, I wonder if they're a little specialised? It is preferable to use these, or add new ones where possible, than hardcoding a version number that would need manually updating each release.