Sphinx: use html_baseurl for setting the canonical URL (#7540)

Fixes readthedocs/readthedocs-sphinx-ext#83

Author: stsewd

docs/guides/canonical.rst

@@ -31,6 +31,16 @@ Check your :guilabel:`Admin` > :guilabel:`Domains` page for the domains that we
 Implementation
 --------------
 
+If you are using :doc:`Sphinx </intro/getting-started-with-sphinx>`,
+Read the Docs will set the value of the html_baseurl_ setting (if isn't already set) to your canonical domain.
+
+.. _html_baseurl: https://www.sphinx-doc.org/page/usage/configuration.html#confval-html_baseurl
+
+If you are using :doc:`MkDocs </intro/getting-started-with-mkdocs>`,
+you can use the site_url_ setting.
+
+.. _site_url: https://www.mkdocs.org/user-guide/configuration/#site_url
+
 If you look at the source code for documentation built after you set your canonical URL,
 you should see a bit of HTML like this:
 

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

@@ -120,6 +120,14 @@ context = {
     'commit': {% if project.repo_type == 'git' %}'{{ commit|slice:"8" }}'{% else %}'{{ commit }}'{% endif %},
 }
 
+# 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
+
+
 {# Provide block for extending context data from child template #}
 {% block extra_context %}{% endblock %}