From d285196f98f4a3eb3af03de54b0a0ee68684d049 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 7 Oct 2020 13:16:22 -0500 Subject: [PATCH] Deprecate instead of removing --- docs/changelog.rst | 2 +- docs/configuring.rst | 16 ++++++++++++++++ sphinx_rtd_theme/__init__.py | 22 ++++++++++++++++++---- sphinx_rtd_theme/layout.html | 5 +++++ sphinx_rtd_theme/theme.conf | 1 + 5 files changed, 41 insertions(+), 5 deletions(-) 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