Get URL's version number inside conf.py?

[hugovk]

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/pythondotorg#1691).

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!

[hugovk]

@JulienPalard Do you know if this docs version is available in conf.py?

[JulienPalard]

Is it possible to get the version from the docs URL (e.g. /3/, /3.12/ or /3.10.7/) in conf.py?

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 single conf.py file.

But docsuilb-scripts could tell, like via an environment variable, "I'm currently building for /3/", and conf.py could pick it up.

[hugovk]

Is it possible to get the version from the docs URL (e.g. /3/, /3.12/ or /3.10.7/) in conf.py?

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?

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.

But docsuilb-scripts could tell, like via an environment variable, "I'm currently building for /3/", and conf.py could pick it up.

That would be great!

[JulienPalard]

If I understand correctly, you'd prefer something like:

3
dev
3.6
3.7
3.8
3.9
3.10 -> 3
3.11
3.12 -> dev

rather than:

3 -> 3.10
dev -> 3.12
3.6
3.7
3.8
3.9
3.10
3.11
3.12

?

If I understand correctly again, this is because you'd like to have an environment variable like: VERSION_IN_URL=3.9 when building for 3.9 but VERSION_IN_URL=3 when building for 3.10?

However, the version in the URL isn't necessarily /3/ [...] so we can't hardcode it.

I'm not sure we can't hardcode it to https://docs.python.org/3/, quoting https://ogp.me/:

og:url - The canonical URL of your object that will be used as its permanent ID in the graph

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 deduce og:title should 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]

If I understand correctly, you'd prefer something like:

3
dev
3.6
3.7
3.8
3.9
3.10 -> 3
3.11
3.12 -> dev

rather than:

3 -> 3.10
dev -> 3.12
3.6
3.7
3.8
3.9
3.10
3.11
3.12

?

Yes, but it's not a strong preference, more of a hunch, I don't fully understand the dark arts of SEO!

If I understand correctly again, this is because you'd like to have an environment variable like: VERSION_IN_URL=3.9 when building for 3.9 but VERSION_IN_URL=3 when building for 3.10?

And yes, because I think it's important to have one of the builds indexed as /3/

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.

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.

I deduce og:title should 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.)

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]

Are you suggesting using /3/ for all of them?

Yes.

That might be fine, and would certainly be easier as we can hardcode it and won't need an environment variable.

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]

Yes, let's start with /3/ for all, thanks!