Get URL's version number inside conf.py? about docsbuild-scripts HOT 7 CLOSED

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

from docsbuild-scripts.

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.

from docsbuild-scripts.

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!

from docsbuild-scripts.

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.)

from docsbuild-scripts.

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.

from docsbuild-scripts.

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?

from docsbuild-scripts.

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

from docsbuild-scripts.