diff --git a/docs/changelog.rst b/docs/changelog.rst
index d99011b5d..aff895e57 100644
--- a/docs/changelog.rst
+++ b/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
======
diff --git a/docs/configuring.rst b/docs/configuring.rst
index dce5b630c..0357a62a4 100644
--- a/docs/configuring.rst
+++ b/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
diff --git a/sphinx_rtd_theme/__init__.py b/sphinx_rtd_theme/__init__.py
index e48d9696d..b9a930e97 100644
--- a/sphinx_rtd_theme/__init__.py
+++ b/sphinx_rtd_theme/__init__.py
@@ -6,12 +6,15 @@
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."""
@@ -19,16 +22,27 @@ def get_html_theme_path():
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}
diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html
index 62807f66b..c53522b25 100644
--- a/sphinx_rtd_theme/layout.html
+++ b/sphinx_rtd_theme/layout.html
@@ -39,6 +39,11 @@
{% endif %}
+ {# CANONICAL URL (deprecated) #}
+ {% if theme_canonical_url and not pageurl %}
+
+ {% endif %}
+
{# CANONICAL URL #}
{%- if pageurl %}
diff --git a/sphinx_rtd_theme/theme.conf b/sphinx_rtd_theme/theme.conf
index 38a75b2ed..e7d9822b2 100644
--- a/sphinx_rtd_theme/theme.conf
+++ b/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