From 5421db86bab89e24e702e08bbb0e4a62fea40e5c Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 7 Oct 2020 12:13:00 -0500 Subject: [PATCH 1/3] Use canonical URL from html_baseurl This is in sphinx itself now https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl, https://github.com/sphinx-doc/sphinx/blob/e886cc21710e23bc53af83d011131828b1020848/sphinx/themes/basic/layout.html#L135-L137 --- docs/changelog.rst | 5 +++++ docs/configuring.rst | 16 +--------------- sphinx_rtd_theme/layout.html | 7 ++++--- sphinx_rtd_theme/theme.conf | 3 +-- 4 files changed, 11 insertions(+), 20 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index caf8575f6..d99011b5d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -5,6 +5,11 @@ Changelog master ====== +Other Changes +------------- + +* The ``canonical_url`` option was removed in favor of Sphinx's ``html_baseurl``. + v0.5.0 ====== diff --git a/docs/configuring.rst b/docs/configuring.rst index 42b64340a..dce5b630c 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 'logo_only': False, 'display_version': True, @@ -101,16 +100,6 @@ 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. - .. confval:: display_version :type: boolean @@ -157,10 +146,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/layout.html b/sphinx_rtd_theme/layout.html index 934406330..62807f66b 100644 --- a/sphinx_rtd_theme/layout.html +++ b/sphinx_rtd_theme/layout.html @@ -38,10 +38,11 @@ {% if favicon %} {% endif %} + {# CANONICAL URL #} - {% if theme_canonical_url %} - - {% endif %} + {%- if pageurl %} + + {%- endif %} {# JAVASCRIPTS #} {%- block scripts %} diff --git a/sphinx_rtd_theme/theme.conf b/sphinx_rtd_theme/theme.conf index fd0521f02..38a75b2ed 100644 --- a/sphinx_rtd_theme/theme.conf +++ b/sphinx_rtd_theme/theme.conf @@ -4,7 +4,6 @@ stylesheet = css/theme.css pygments_style = default [options] -canonical_url = analytics_id = collapse_navigation = True sticky_navigation = True @@ -15,4 +14,4 @@ logo_only = display_version = True prev_next_buttons_location = bottom style_external_links = False -style_nav_header_background = \ No newline at end of file +style_nav_header_background = From 5f17c4aa0840824f09f6ca7cb69d2ef86c96ae9b Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 7 Oct 2020 13:16:22 -0500 Subject: [PATCH 2/3] Deprecate instead of removing --- docs/changelog.rst | 2 +- docs/configuring.rst | 16 ++++++++++++++++ sphinx_rtd_theme/__init__.py | 21 +++++++++++++++++---- sphinx_rtd_theme/layout.html | 5 +++++ sphinx_rtd_theme/theme.conf | 1 + 5 files changed, 40 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..54a3591d1 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,26 @@ 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 From 7ee82f5d6dc09fd1d296bd0527236d838cc00884 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 7 Oct 2020 13:25:08 -0500 Subject: [PATCH 3/3] Make it work with old versions --- sphinx_rtd_theme/__init__.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/sphinx_rtd_theme/__init__.py b/sphinx_rtd_theme/__init__.py index 54a3591d1..75e6e751a 100644 --- a/sphinx_rtd_theme/__init__.py +++ b/sphinx_rtd_theme/__init__.py @@ -8,7 +8,13 @@ from sphinx import version_info from sphinx.locale import _ -from sphinx.util.logging import getLogger + +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__ @@ -41,7 +47,6 @@ def setup(app): # 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) + app.connect('config-inited', config_initiated) return {'parallel_read_safe': True, 'parallel_write_safe': True}