Repository navigation
Get URL's version number inside conf.py? #137
Description
Question
Is it possible to get the version from the docs URL (e.g. /3/, /3.12/ or /3.10.7/) in conf.py?
Why?
I'm looking at adding OpenGraph metadata to the docs to help with SEO (see python/docs-community#179).
And there's a handy Sphinx extension that can help: https://pypi.org/project/sphinxext-opengraph/
We need to add config like ogp_site_url = "http://example.org/"
For example:
ogp_site_url = "https://docs.python.org/3/"Produces something like:
<meta property="og:url" content="https://docs.python.org/3/library/csv.html" />However, the version in the URL isn't necessarily /3/, it could include minor version (https://docs.python.org/3.12/) or even patch version (https://docs.python.org/release/3.10.7/), so we can't hardcode it.
Is this path version available in conf.py?
conf.py already has:
# We look for the Include/patchlevel.h file in the current Python source tree
# and replace the values accordingly.
import patchlevel
version, release = patchlevel.get_version_info()But these are like 3.12, 3.12.0a0, and don't necessarily match the URL version (which could be any of major[.minor[.patch]].
Thanks!
Activity
hugovk commentedon Oct 8, 2022
@JulienPalard Do you know if this docs version is available in
conf.py?JulienPalard commentedon Oct 13, 2022
That's not trivial, first because
/3/is in fact a symlink to a specific build, so we can't generate different HTML files for/3/and/3.10/(as currently the 3.10 is the stable one).So maybe first: do we need a distinct build for
/3/and/3.10/instead of symlinks?If yes, we have another problem: the exact same tree would have to give two distinct values (
/3/and/3.10/) for the "version as seen in the URL", so we can't have this in a singleconf.pyfile.But docsuilb-scripts could tell, like via an environment variable, "I'm currently building for
/3/", andconf.pycould pick it up.hugovk commentedon Oct 13, 2022
No, I don't think we need to worry about that, and especially not for a first iteration. I think it would be better to use
/3/for both rather than/3.10/for both, if we have the option.That would be great!
JulienPalard commentedon Oct 14, 2022
If I understand correctly, you'd prefer something like:
rather than:
?
If I understand correctly again, this is because you'd like to have an environment variable like:
VERSION_IN_URL=3.9when building for 3.9 butVERSION_IN_URL=3when building for 3.10?I'm not sure we can't hardcode it to
https://docs.python.org/3/, quotinghttps://ogp.me/:For me the canonical URL of the content delivered by https://docs.python.org/3.9/library/functions.html is https://docs.python.org/3/library/functions.html.
I've searched (a few seconds) on the internet and found that some SEO tools can complain if the canonical URL does not match the og:url, that make another point to just use
/3/, as we do in the canonical URL. I deduceog:titleshould match the<title>tag and so on?(After reading ogp.me and written this, I have to admit I don't understand OpenGraph, isn't it just duplicating the
<title>tag, the<link rel="canonical"and the<meta name="description"? Duplicating things does not feel right at all, it feels bloaty, and I don't like bloaty pages. I mean, if someone's code out here is not able to extract titles from the<title>tag, they'd better go fix their code instead of asking us to copy-paste our titles in another tag.)hugovk commentedon Oct 14, 2022
Yes, but it's not a strong preference, more of a hunch, I don't fully understand the dark arts of SEO!
And yes, because I think it's important to have one of the builds indexed as
/3/Are you suggesting using
/3/for all of them? That might be fine, and would certainly be easier as we can hardcode it and won't need an environment variable.In many cases they will, but it's possible they can be different as they're slightly different, semantically speaking. One is the title of the webpage, for browsers, the other is the title of the thing to be shared, for Facebook and so on.
For example, Stack Overflow has:
title: "facebook opengraph - In a website, what is the value of og:title as opposed to a plain title element? - Stack Overflow"og:title: "In a website, what is the value of og:title as opposed to a plain title element?"For us, they will be the same, but I don't think a few extra characters of plaintext is a problem given the size of webpages. Images and weighty JS frameworks are more of a concern.
JulienPalard commentedon Oct 14, 2022
Yes.
Let's start with that, and if there's strong evidence that we need something more complicated we'll do.
So no commits are needed docsbuild-script side, only cpython side, I think this issue can be closed?
hugovk commentedon Oct 15, 2022
Yes, let's start with
/3/for all, thanks!