diff --git a/docs/changelog.rst b/docs/changelog.rst
index f178469a6..72ddfb2b0 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -5,11 +5,17 @@ Changelog
master
======
+Other Changes
+-------------
+
+* The ``canonical_url`` option was deprecated in favor of Sphinx's ``html_baseurl``.
+
New Features
------------
* New theme option to enable anonymous ip addresses when using Google Analytics (#889)
+
v0.5.0
======
diff --git a/docs/configuring.rst b/docs/configuring.rst
index 85cafffac..b51e03e24 100644
--- a/docs/configuring.rst
+++ b/docs/configuring.rst
@@ -13,7 +13,6 @@ For example:
.. code:: python
html_theme_options = {
- 'canonical_url': '',
'analytics_id': 'UA-XXXXXXX-1', # Provided by Google in your dashboard
'analytics_anonymize_ip': False,
'logo_only': False,
@@ -119,6 +118,12 @@ Miscellaneous options
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
@@ -165,10 +170,7 @@ Miscellaneous options
:default: ``#2980B9``
Changes the background of the search area in the navigation bar. The value
- can be anything valid in a CSS `background` property.
-
-.. _canonical URL: https://en.wikipedia.org/wiki/Canonical_link_element
-
+ can be anything valid in a CSS `background` property.
File-wide metadata
==================
diff --git a/sphinx_rtd_theme/__init__.py b/sphinx_rtd_theme/__init__.py
index e48d9696d..75e6e751a 100644
--- a/sphinx_rtd_theme/__init__.py
+++ b/sphinx_rtd_theme/__init__.py
@@ -6,12 +6,21 @@
from os import path
-import sphinx
+from sphinx import version_info
+from sphinx.locale import _
+
+try:
+ # Avaliable from Sphinx 1.6
+ from sphinx.util.logging import getLogger
+except ImportError:
+ from 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 +28,25 @@ 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 90c409514..c8cab2560 100644
--- a/sphinx_rtd_theme/layout.html
+++ b/sphinx_rtd_theme/layout.html
@@ -38,11 +38,17 @@
{% if favicon %}
{% endif %}
- {# CANONICAL URL #}
- {% if theme_canonical_url %}
+
+ {# CANONICAL URL (deprecated) #}
+ {% if theme_canonical_url and not pageurl %}
{% endif %}
+ {# CANONICAL URL #}
+ {%- if pageurl %}
+
+ {%- endif %}
+
{# JAVASCRIPTS #}
{%- block scripts %}