Deprecate instead of removing

docs/changelog.rst

@@ -8,7 +8,7 @@ master
 Other Changes
 -------------
 
-* The ``canonical_url`` option was removed in favor of Sphinx's ``html_baseurl``.
+* The ``canonical_url`` option was deprecated in favor of Sphinx's ``html_baseurl``.
 
 v0.5.0
 ======

docs/configuring.rst

@@ -100,6 +100,22 @@ Miscellaneous options
     If specified, Google Analytics' javascript is included in your pages.
     Set the value to the ID provided to you by google (like ``UA-XXXXXXX``).
 
+.. confval:: canonical_url
+
+    :type: URL
+
+    This will specify a `canonical URL`_ meta link element to tell search
+    engines which URL should be ranked as the primary URL for your
+    documentation. This is important if you have multiple URLs that your
+    documentation is available through. The URL points to the root path of the
+    documentation and requires a trailing slash.
+
+    .. deprecated:: 0.6.0
+
+       Use :confval:`sphinx:html_baseurl` instead.
+
+    .. _canonical URL: https://en.wikipedia.org/wiki/Canonical_link_element
+
 .. confval:: display_version
 
     :type: boolean

sphinx_rtd_theme/__init__.py

@@ -6,29 +6,43 @@
 
 from os import path
 
-import sphinx
-
+from sphinx import version_info
+from sphinx.locale import _
+from sphinx.util.logging import getLogger
 
 __version__ = '0.5.0'
 __version_full__ = __version__
 
+logger = getLogger(__name__)
+
 
 def get_html_theme_path():
     """Return list of HTML theme paths."""
     cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
     return cur_dir
 
 
+def config_initiated(app, config):
+    theme_options = config.html_theme_options or {}
+    if theme_options.get('canonical_url'):
+        logger.warning(
+            _('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
+        )
+
+
+
 # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
-    if sphinx.version_info >= (1, 6, 0):
+    if version_info >= (1, 6, 0):
         # Register the theme that can be referenced without adding a theme path
         app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))
 
-    if sphinx.version_info >= (1, 8, 0):
+    if version_info >= (1, 8, 0):
         # Add Sphinx message catalog for newer versions of Sphinx
         # See http://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_message_catalog
         rtd_locale_path = path.join(path.abspath(path.dirname(__file__)), 'locale')
         app.add_message_catalog('sphinx', rtd_locale_path)
 
+    app.connect('config-inited', config_initiated)
+
     return {'parallel_read_safe': True, 'parallel_write_safe': True}

sphinx_rtd_theme/layout.html

@@ -39,6 +39,11 @@
     <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
   {% endif %}
 
+  {# CANONICAL URL (deprecated) #}
+  {% if theme_canonical_url and not pageurl %}
+    <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html"/>
+  {% endif %}
+
   {# CANONICAL URL #}
   {%- if pageurl %}
     <link rel="canonical" href="{{ pageurl|e }}" />

sphinx_rtd_theme/theme.conf

@@ -4,6 +4,7 @@ stylesheet = css/theme.css
 pygments_style = default
 
 [options]
+canonical_url =
 analytics_id =
 collapse_navigation = True
 sticky_navigation = True