Deprecate canonical_url in favor of html_baseurl (#178)

Rely on html_baseurl for the canonical url instead.
The canonical url is already set in the basic theme

https://github.com/sphinx-doc/sphinx/blob/4e9d1553968653df6699b20afc22b73eb3280185/sphinx/themes/basic/layout.html#L130-L132

That takes into account pages using the dirhtml builder
instead of always adding the `html` extension.
This was introduced in sphinx 1.8.

alabaster/layout.html

@@ -6,7 +6,9 @@
   {% if theme_touch_icon %}
     <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
   {% endif %}
-  {% if theme_canonical_url %}
+
+  {# Deprecated in favor of html_baseurl (pageurl). This is already set in the basic theme #}
+  {% if theme_canonical_url and not pageurl %}
     <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html" />
   {% endif %}
 {% endblock %}

docs/customization.rst

@@ -71,12 +71,15 @@ Settings related to text display, logo, etc.
 
 * ``body_text_align``: Which CSS ``text-align`` value to use for body text
   (if there is any.)
-* ``canonical_url``: If set, is used as the base URL (set before the relative
+* ``canonical_url``: **Deprecated**, please use the html_baseurl_ Sphinx option instead.
+  If set, is used as the base URL (set before the relative
   path/pagename) for a ``<link rel="canonical">`` `canonical URL
   <https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls>`_ header tag.
 
   .. note:: This value must end with a trailing slash.
 
+  .. _html_baseurl: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl
+
 * ``description``: Text blurb about your project, to appear under the logo.
 * ``description_font_style``: Which CSS ``font-style`` to use for description
   text.