Sphinx builder: Use READTHEDOCS_CANONICAL_URL as html_baseurl

[benjaoming]

Proof of concept:

• Docs: Experiment with canonical url using READTHEDOCS_CANONICAL_URL #10224
• Use correct canonical URL while building docs jupyter/notebook#6829

If this turns out to work well, I think we should escalate the pattern to replace the current implementation:

readthedocs.org/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl

Lines 151 to 156 in f02bc09

	# For sphinx >=1.8 we can use html_baseurl to set the canonical URL.
	# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl
	if version_info >= (1, 8):
	if not globals().get('html_baseurl'):
	html_baseurl = context['canonical_url']
	context['canonical_url'] = None

tldr; Why is it broken? What changed?

It can look odd that we have a behavior on Read the Docs Sphinx builder that looks broken and keeps coming up as an issue... I think it's an honest well-meaning implementation that's currently there. The outside understanding of what "canonical" means has just slowly pushed towards a new understanding.

The current implementation of "canonical URL", results in a meta tag canonical that simply points to the default version of a documentation, i.e. /en/stable.

It's possible to have the understanding that a "canonical URL" should always point to the default version. And that might have been the honest cause for the current implementation. But that's unfortunately an understanding of websites that doesn't match current-day usage of the canonical meta tag.

More and more chat clients and social media are reading the "canonical URL" in order to get a cleaned up version for a link, something resembling a "permalink". We started seeing the issue more and more since Mastodon uses the canonical meta field when parsing link data for preview cards.

So this ultimately means that preview cards and other auto-generated versions will not point to the same version as the link that got shared. And that's just wrong from a user's POV.

[ashwinvis]

I saw this use case which looks at the SITEMAP_URL_BASE env variable.

https://github.com/pydata/pydata-sphinx-theme/blob/d98350b581b5dd804b918b1f6c82a51964957df8/docs/conf.py#L62

I wonder if overriding this might be an issue?

[benjaoming]

Interesting! It looks safe from RTD injection since it's already guarded by a conditional: https://github.com/pydata/pydata-sphinx-theme/blob/d98350b581b5dd804b918b1f6c82a51964957df8/docs/conf.py#L59

If html_baseurl gets defined, RTD won't override it.

It's a bit hard to say what a project could need for development settings. Some might view local files with file:/// and some might be running sphinx-autobuild on http://127.0.0.1:8000. I think the safe default html_baseurl is simply /. But it's ultimately up to the project that wants to define it 👍

[humitos]

We are moving away from the idea of adding/changing "magic" on our build process. Eventually, we should remove it all and only document how to use our environment variables properly on different doctools as #10246 mention. I'm closing this issue for now but we can re-open if we want to.