From f2bbe7dc1b9f144da4e16a84650c10bca00a2118 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 21 Aug 2023 20:38:57 +0200 Subject: [PATCH] update to sphinx theme master 2.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 2.0 milestone: drop supported versions The new policy is: - Python >=3.6 - Sphinx >= 5 - HTML4 and HTML5 writer - docutils >= 0.14, < 0.19 * Update roadmap after discussion By the beginning of 2024 we should support newer Sphinx versions and HTML5 only. * Remove Python 2.7 from CircleCI * Run only supported versions on Python 3.11 * Update with feedback from review * Update documentation to match our support * Add Sphinx 6.2 that was missing * Update tox/circleci to work * Revert tox command * Drop support for HTML4 and keep `-qa` testing - drop support for HTML4 on 2.0 - keep `-qa` TOX environment to be able to compare feature branches - emit `logger.errors` on Python 2 and html_writer4=True - require Sphinx >= 5.0 - remove logic for old Sphinx versions * Update Tox and CircleCI * Update contributing page to match our plans --------- Co-authored-by: Anthony Johnson Release 2.0.0rc1 (#1510) * Release 2.0.0rc1 * Update npm lock file Bump to next release 2.0.0rc2 (#1511) Docs: Remove "git install" method from instructions (#1375) * Remove instructions "encouraging" to install directly from git * Update changelog: Add reminder that people should not install directly from git * Update docs/changelog.rst --------- Co-authored-by: Manuel Kaufmann Visual test with Firefox and tox (#1513) * Visual test with Firefox and tox Allows developer to run ``` tox -e py310-sphinx72-firefox ``` This will run the tests and open a Firefox after building the demo site showing the `demo/demo.html` page on it. Then, you can also run: ``` tox -e py310-sphinx61-firefox ``` and compare the visual differences. Idea copied from #1388 Closes #1388 * Default value for `DISPLAY` and `--new-tab` * Simplify the idea :) Remove Python2 leftovers (#1514) Docs: update Read the Docs config (#1518) Use the latest config file style. Set data-content_root for Sphinx ≥ 7.2 (#1507) This attribute is now required by searchtools.js: https://github.com/sphinx-doc/sphinx/blob/v7.2.2/sphinx/themes/basic/static/searchtools.js#L65 When it's not set, loading search results via AJAX will be broken because the JS code will attempt to load paths like /undefinedfoo.html. Co-authored-by: Manuel Kaufmann Use `css_tag` helper to inject CSS files (#1519) * Use `css_tag` helper to inject CSS files * Typo Add support for `docutils==0.20.x` (#1517) Closes #1516 Release 2.0rc2 (#1520) Version bump for 2.0rc3 development (#1521) Next development version is 2.0rc3 for now, but more likely 2.1rc1 Fix #1522: fix `'str' object has no attribute 'attributes'` (#1528) * Fix #1522: fix attribute error if css is str * Revert "Fix #1522: fix attribute error if css is str" This reverts commit b22a77f35a4a966dc686e8681753cd54cbb91a16. * Use `css_tag` only for standard CSS files from Sphinx ... and keep using the custom `link` HTML tag for CSS files included via the HTML theme option `extra_css_files`. * Normalize template variables --------- Co-authored-by: Manuel Kaufmann Co-authored-by: Anthony Johnson Release 2.0.0rc3 (#1535) Increment for next potential release (#1536) Fix AttributeError when one of `css_files` is a string (#1537) Fix AttributeError when one of css_files is a string Release 2.0.0rc4 (#1538) Bump for next potential release, 2.0.0rc5 (#1539) Release 2.0 final (#1544) --- .circleci/config.yml | 28 ++--- .readthedocs.yml | 6 +- docs/changelog.rst | 22 +++- docs/contributing.rst | 51 ++++----- docs/demo/api.rst | 34 ++---- docs/demo/test_py_module/test_py27.py | 152 -------------------------- docs/development.rst | 55 +++++++--- docs/installing.rst | 18 --- package-lock.json | 2 +- package.json | 2 +- setup.cfg | 10 +- setup.py | 2 +- sphinx_rtd_theme/__init__.py | 32 ++---- sphinx_rtd_theme/layout.html | 15 +-- tox.ini | 49 ++------- 15 files changed, 150 insertions(+), 328 deletions(-) delete mode 100644 docs/demo/test_py_module/test_py27.py diff --git a/.circleci/config.yml b/.circleci/config.yml index 7371a2f16..d7aa9d7ee 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -11,10 +11,14 @@ commands: type: string sphinx-version: type: string - default: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,latest" + default: "latest" steps: - checkout - - run: pip install --user tox~=3.27 + # We cannot upgrade to Tox4 because running generative environments doesn't work. + # I guess it has changed its syntax or similar. + # $ tox run -e "py310-sphinx{50,51}" + # ROOT: HandledError| provided environments not found in configuration file: ['51}'] + - run: pip install --user 'tox~=3.27' - run: tox -e "<>-sphinx{<>}" run-build: description: "Ensure built assets are up to date" @@ -40,53 +44,48 @@ jobs: - image: 'cimg/python:3.9-node' steps: - run-build: {} - py27: - docker: - - image: 'cimg/python:2.7' - steps: - - run-tox: - version: py27 - sphinx-version: "17,18" py36: docker: - image: 'cimg/python:3.6' steps: - run-tox: version: py36 + sphinx-version: "50,51,52,53" py37: docker: - image: 'cimg/python:3.7' steps: - run-tox: version: py37 + sphinx-version: "50,51,52,53" py38: docker: - image: 'cimg/python:3.8' steps: - run-tox: version: py38 - sphinx-version: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest" + sphinx-version: "50,51,52,53,60,61,62,70,71,latest" py39: docker: - image: 'cimg/python:3.9' steps: - run-tox: version: py39 - sphinx-version: "18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52,60,latest" + sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest" py310: docker: - image: 'cimg/python:3.10' steps: - run-tox: version: py310 - sphinx-version: "42,43,44,45,50,51,52,53,60,latest" + sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest" py311: docker: - image: 'cimg/python:3.11' steps: - run-tox: version: py311 - sphinx-version: "53,60,latest" + sphinx-version: "53,60,61,62,70,71,72,latest,dev" workflows: version: 2 @@ -111,6 +110,3 @@ workflows: - py36: requires: - build - - py27: - requires: - - build diff --git a/.readthedocs.yml b/.readthedocs.yml index 21d235821..e0f00d709 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,7 +1,11 @@ version: 2 +build: + os: "ubuntu-22.04" + tools: + python: "3.10" + python: - version: 3.8 install: - requirements: docs/requirements.txt - method: pip diff --git a/docs/changelog.rst b/docs/changelog.rst index fedb435ef..bf268488d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,7 +4,27 @@ Changelog .. seealso:: :ref:`howto_upgrade` -.. |theme_version| replace:: 1.3.0 +.. |theme_version| replace:: 2.0.0 + +.. _release-2.0.0: + +2.0.0 +===== + +Added +----- + +* Support for Sphinx versions ``6.x`` and ``7.x`` +* Support for docutils ``<=0.20`` + +Deprecations +------------ + +* The HTML4 writer is now officially deprecated. An error will be thrown if your + project configuration still uses the HTML4 writer. +* Support for Sphinx versions < 5.0 was removed. +* In addition, our supported dependencies will match the dependencies from our + lowest supported Sphinx release, version 5.0: Python >= 3.6 and docutils > 0.14 and < 0.19 .. _release-1.3.0: diff --git a/docs/contributing.rst b/docs/contributing.rst index 41b91652c..dd2eac194 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -103,20 +103,18 @@ compatibility. The following cases need to be tested with changes to CSS or JavaScript: -* Multiple, modern browsers should be tested. We officially support back - to IE11 at the moment -* Multiple viewport sizes should be tested for changes. We support large, - tablet, and mobile viewport sizes -* We currently support both the Sphinx HTML4 writer and HTML5 writer. This makes - for some complex CSS selectors -* Multiple major versions of Sphinx should be tested. We currently support back - to Sphinx version ``1.6`` +* Multiple, modern browsers should be tested. +* Multiple viewport sizes should be tested for changes. + We support large, tablet, and mobile viewport sizes +* We currently support only HTML5 writer. +* Multiple major versions of Sphinx should be tested. + We currently support Sphinx ``>=5.0`` It's easiest to test combinations of dependency versions using ``tox``: .. code:: console - % tox -e py3-sphinx34-html4 + % tox -e py310-sphinx62 If the tests and build are successful, you can view the built documentation at the directory noted by Sphinx: @@ -125,9 +123,9 @@ the directory noted by Sphinx: build succeeded, 10 warnings. - The HTML pages are in .tox/py3-sphinx34-html4/tmp/html. + The HTML pages are in .tox/py310-sphinx62/tmp/html. ___________________________ summary ___________________________ - py3-sphinx34-html4: commands succeeded + py310-sphinx62: commands succeeded congratulations :) You can then open up this path with a series of browsers to test. @@ -137,12 +135,12 @@ multiple ``tox`` environments, and open both up for comparison: .. code:: console - % tox -e py3-sphinx34-html4 + % tox -e py310-sphinx62 ... - % tox -e py3-sphinx34-html5 + % tox -e py310-sphinx53 ... - % firefox .tox/py3-sphinx34-html4/tmp/html/index.html - % firefox .tox/py3-sphinx34-html5/tmp/html/index.html + % firefox .tox/py310-sphinx62/tmp/html/index.html + % firefox .tox/py310-sphinx53/tmp/html/index.html You can also use a separate ``tox`` environment for building output to compare against. All of the ``tox`` environments have an additional postfix, ``-qa``, to @@ -155,28 +153,25 @@ For example, to test against the tag ``0.5.2``: .. code:: console % git checkout 0.5.2 - % tox -e py3-sphinx34-html4-qa + % tox -e py310-sphinx53-qa ... % git checkout feature/example-pull-request - % tox -e py3-sphinx34-html4 + % tox -e py310-sphinx53 ... - % firefox .tox/py3-sphinx34-html4-qa/tmp/html/index.html - % firefox .tox/py3-sphinx34-html4/tmp/html/index.html + % firefox .tox/py310-sphinx53-qa/tmp/html/index.html + % firefox .tox/py310-sphinx53/tmp/html/index.html Currently, the most important environments to QA are: .. This list is purposely shorter than what we describe above. If we test all of - the cases above, we'll be here all day. Python 3, HTML4/5 writer, and latest + the cases above, we'll be here all day. Python 3, and latest minor of each major Sphinx release should give us enough work. -* ``py3-sphinx18-html4`` -* ``py3-sphinx18-html5`` -* ``py3-sphinx24-html4`` -* ``py3-sphinx24-html5`` -* ``py3-sphinx35-html4`` -* ``py3-sphinx35-html5`` -* ``py3-sphinx41-html4`` -* ``py3-sphinx41-html5`` +* ``py310-sphinx53`` +* ``py310-sphinx62`` +* ``py310-sphinx72`` +* ``py310-sphinxlatest`` +* ``py310-sphinxdev`` Translations ============ diff --git a/docs/demo/api.rst b/docs/demo/api.rst index c077a0421..6c3163d07 100644 --- a/docs/demo/api.rst +++ b/docs/demo/api.rst @@ -7,19 +7,11 @@ API documentation and generated content :mod:`test_py_module` ===================== -.. only:: python3 +.. automodule:: test_py_module.test + :members: + :private-members: + :special-members: - .. automodule:: test_py_module.test - :members: - :private-members: - :special-members: - -.. only:: python2 - - .. automodule:: test_py_module.test_py27 - :members: - :private-members: - :special-members: C++ API ======= @@ -153,18 +145,8 @@ Sphinx Extensions sphinx.ext.autosummary ---------------------- -.. only:: python3 - - .. autosummary:: - - test_py_module.test.add_numbers - test_py_module.test.subtract_numbers - test_py_module.test.Foo - -.. only:: python2 - - .. autosummary:: +.. autosummary:: - test_py_module.test_py27.add_numbers - test_py_module.test_py27.subtract_numbers - test_py_module.test_py27.Foo + test_py_module.test.add_numbers + test_py_module.test.subtract_numbers + test_py_module.test.Foo diff --git a/docs/demo/test_py_module/test_py27.py b/docs/demo/test_py_module/test_py27.py deleted file mode 100644 index bc011e272..000000000 --- a/docs/demo/test_py_module/test_py27.py +++ /dev/null @@ -1,152 +0,0 @@ -# -*- coding: utf-8 -*- -""" -This module will overwrite test.py for Python 2.7 builds. -Type signatures cause autodoc to break in Python 2.7 documentation builds, so they are removed here. - -Test Module for sphinx_rtd_theme.""" - - -class Foo: - - """Docstring for class Foo. - - This text tests for the formatting of docstrings generated from output - ``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the - ``
``, and ``
`` tags. Also, ```` is used for class, method names - and etc, but those will *always* have the ``.descname`` or - ``.descclassname`` class. - - Term - It is also possible to include definitions inside docstrings. - They should be styled as a normal definition list. - - :Field List: - It is also possible to include definitions inside docstrings. - They should be styled as a normal definition list. - - .. [1] A footnote contains body elements, consistently indented by at - least 3 spaces. - - .. [Citation] A citation contains body elements, consistently indented by at - least 3 spaces. - - Normal ```` (like the I just wrote here) needs to be shown with - the same style as anything else with ````this type of markup````. - - It's common for programmers to give a code example inside of their - docstring:: - - from test_py_module import Foo - - myclass = Foo() - myclass.dothismethod('with this argument') - myclass.flush() - - print(myclass) - - - Here is a link to :py:meth:`capitalize`. - Here is a link to :py:meth:`__init__`. - - """ - - #: Doc comment for class attribute Foo.bar. - #: It can have multiple lines. - bar = 1 - - flox = 1.5 #: Doc comment for Foo.flox. One line only. - - baz = 2 - """Docstring for class attribute Foo.baz.""" - - def __init__(self, qux, spam=False): - """Start the Foo. - - :param qux: The first argument to initialize class. - :type qux: string - :param spam: Spam me yes or no... - :type spam: bool - - """ - #: Doc comment for instance attribute qux. - self.qux = 3 - - self.spam = 4 - """Docstring for instance attribute spam.""" - - def add(self, val1, val2): - """Return the added values. - - :param val1: First number to add. - :type val1: int - :param val2: Second number to add. - :type val2: int - :rtype: int - - The parameters of this method are described in the parameter list. - """ - - return val1 + val2 - - def capitalize(self, myvalue): - """Return a string as uppercase. - - :param myvalue: String to change - :type myvalue: string - :rtype: string - - """ - - return myvalue.upper() - - def another_function(self, a, b, **kwargs): - """ - Here is another function. - - :param a: The number of green hats you own. - :type a: int - - :param b: The number of non-green hats you own. - :type b: int - - :param kwargs: Additional keyword arguments. Each keyword parameter - should specify the name of your favorite cuisine. - The values should be floats, specifying the mean price - of your favorite dish in that cooking style. - :type kwargs: float - - :returns: A 2-tuple. The first element is the mean price of all dishes - across cuisines. The second element is the total number of - hats you own: :math:`a + b`. - :rtype: tuple - - :raises ValueError: When ``a`` is not an integer. - - .. versionadded:: 1.0 - This was added in 1.0 - .. versionchanged:: 2.0 - This was changed in 2.0 - .. deprecated:: 3.0 - This is deprecated since 3.0 - """ - return sum(kwargs.values()) / len(kwargs), a + b - - -def add_numbers(a, b): - """Add two numbers together - - :param a: The first number - :param b: The second number - - Here is some more text. - """ - return a + b - - -def subtract_numbers(a, b): - """Subtract two numbers - - :param a: The first number - :param b: The second number - """ - return a - b diff --git a/docs/development.rst b/docs/development.rst index 598e6ae47..c4ee9a43c 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -42,7 +42,7 @@ Internet Explorer (any OS, versions <=10) Internet Explorer (any OS, version 11) We currently only partially support IE11, and only test for major bugs. - Support will be removed in the :ref:`roadmap-release-2.0.0` release. + Support will be removed in the :ref:`roadmap-release-3.0.0` release. Opera (any OS, any version) **Community support only.** We do not receive enough traffic with this @@ -62,11 +62,20 @@ The theme officially supports the following dependencies in your Sphinx project: * - Dependency - Versions * - Python - - 2.7 or 3.6 or greater + - 3.6 or greater * - Sphinx - - 1.7 up to at least 4.1 + - 5 or greater * - docutils - - Up to 0.17 + - >= 0.14, < 0.19 + +.. deprecated:: 2.0 + Sphinx < 5 support removed + +.. deprecated:: 2.0 + Python < 3.6 support removed + +.. deprecated:: 2.0 + docutils < 0.14 support removed .. versionadded:: 1.0 Sphinx 4.0 support added @@ -143,15 +152,14 @@ like Sphinx 1.8, HTML4, or required support for IE11. 2.0.0 ~~~~~ -:Planned release date: 2022 Q1 +:Planned release date: 2023 Q3 -This release will mark the beginning of a new round of feature development, as -well as a number of backward incompatible changes and deprecations. +This release will drop support for old Python and Sphinx versions. -Of note, the following backwards incompatible changes are planned for this +Note the following backwards incompatible changes are planned for this release: -Sphinx 1.x, Sphinx 2.x, and Docutils 0.16 will not be tested +Python < 3.6, Sphinx < 5 and Docutils < 0.14 will not be tested Official support will drop for these version, though they may still continue to work. Theme developers will not be testing these versions any longer. @@ -160,7 +168,7 @@ HTML4 support will be removed and builds attempting to use the HTML4 writer will fail. If you are still using the HTML4 writer, or have the ``html4_writer = True`` option in your Sphinx configuration file, you will need to either remove this option or pin - your dependency to ``sphinx_rtd_theme<=2.0.0`` until you can. + your dependency to ``sphinx_rtd_theme<=3`` until you can. This option was suggested in the past to work around issues with HTML5 support and should no longer be required to use a modern combination of this @@ -171,10 +179,31 @@ HTML4 support will be removed 3.0.0 ~~~~~ -This release is not yet planned, however there are plans to potentially replace -Wyrm with Bootstrap in a release after 2.0. +:Planned release date: 2024 Q1 + +This release is not yet fully planned. +However, we already know that we will be dropping support for older version of different dependencies and browsers. + +Sphinx 5, Python < 3.8 and docutils < 0.18 support will be removed + Sphinx 5 is the latest version that supports Python 3.6 and 3.7, + and docutils < 0.18. + +Internet Explorer 11 support will be dropped + `IE11 reached end of life on 14 June 20222 `_, + so we are not supporting it on newer versions, + starting on 3.0.0. + +.. _roadmap-release-4.0.0: + +4.0.0 +~~~~~ + +:Planned release date: 2024 Q2 + +This release is not yet planned. +There are plans to potentially replace Wyrm with Bootstrap in a release after 3.0. Also tentatively planned for this release is finally removing built CSS and JavaScript assets from our repository. This will remove the ability to install the package directly from GitHub, and instead users will be advised to install -development releases from PyPI +development releases from PyPI. diff --git a/docs/installing.rst b/docs/installing.rst index d9a5d00f9..87c0c6678 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -58,21 +58,3 @@ Otherwise, pip will ignore pre-releases. Add for instance ``sphinx-rtd-theme==1. More information is available in Read the Docs' documentation on :doc:`rtd:guides/reproducible-builds`. - -Via Git or Download -------------------- - -.. warning:: - - Installing directly from the repository source is deprecated and is not - recommended. Static assets won't be included in the repository starting in - release :ref:`roadmap-release-3.0.0`. - -Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at -``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx -``conf.py`` file: - -.. code:: python - - html_theme = "sphinx_rtd_theme" - html_theme_path = ["_themes", ] diff --git a/package-lock.json b/package-lock.json index b73a825f8..642f4b739 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "sphinx_rtd_theme", - "version": "1.3.0", + "version": "2.0.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 2aa6a6804..b5c7f0758 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "sphinx_rtd_theme", "main": "js/theme.js", - "version": "1.3.0", + "version": "2.0.0", "scripts": { "dev": "webpack-dev-server --open --config webpack.dev.js", "build": "webpack --config webpack.prod.js", diff --git a/setup.cfg b/setup.cfg index d32b8eceb..bbe705afe 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 1.3.0 +current_version = 2.0.0 commit = false tag = false parse = (?P\d+)\.(?P\d+)\.(?P\d+)((?P[a-z]+)(?P\d+))? @@ -27,8 +27,8 @@ classifiers = Environment :: Console Environment :: Web Environment Intended Audience :: Developers - Programming Language :: Python :: 2.7 Programming Language :: Python :: 3 + Programming Language :: Python :: 3 :: Only Programming Language :: Python :: 3.6 Programming Language :: Python :: 3.7 Programming Language :: Python :: 3.8 @@ -43,10 +43,10 @@ classifiers = include_package_data = True zip_safe = False packages = sphinx_rtd_theme -python_requires = >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.* +python_requires = >=3.6 install_requires = - sphinx >=1.6,<8 - docutils <0.19 + sphinx >=5,<8 + docutils <0.21 sphinxcontrib-jquery >=4,<5 tests_require = pytest diff --git a/setup.py b/setup.py index 5a2a7d914..f11bbc800 100644 --- a/setup.py +++ b/setup.py @@ -86,7 +86,7 @@ def run(self): setup( - version='1.3.0', + version='2.0.0', cmdclass={ 'update_translations': UpdateTranslationsCommand, 'transifex': TransifexCommand, diff --git a/sphinx_rtd_theme/__init__.py b/sphinx_rtd_theme/__init__.py index f9cb25627..2ce88a259 100644 --- a/sphinx_rtd_theme/__init__.py +++ b/sphinx_rtd_theme/__init__.py @@ -12,7 +12,7 @@ from sphinx.util.logging import getLogger -__version__ = '1.3.0' +__version__ = '2.0.0' __version_full__ = __version__ logger = getLogger(__name__) @@ -40,15 +40,11 @@ def extend_html_context(app, pagename, templatename, context, doctree): # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package def setup(app): if python_version[0] < 3: - logger.warning("Python 2 is deprecated with sphinx_rtd_theme, update to Python 3") - app.require_sphinx('1.6') - if sphinx_version <= (2, 0, 0): - logger.warning("Sphinx 1.x is deprecated with sphinx_rtd_theme, update to Sphinx 2.x or greater") - if not app.config.html_experimental_html5_writer: - logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme") - else: - if app.config.html4_writer: - logger.warning("'html4_writer' is deprecated with sphinx_rtd_theme") + logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.") + + app.require_sphinx('5.0') + if app.config.html4_writer: + logger.error("'html4_writer' is not supported with sphinx_rtd_theme.") # Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that # the sphinxcontrib-jquery extension is enabled. @@ -66,18 +62,14 @@ def setup(app): # 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 >= (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) + # 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) # sphinx emits the permalink icon for headers, so choose one more in keeping with our theme - if sphinx_version >= (3, 5, 0): - app.config.html_permalinks_icon = "\uf0c1" - else: - app.config.html_add_permalinks = "\uf0c1" + app.config.html_permalinks_icon = "\uf0c1" # Extend the default context when rendering the templates. app.connect("html-page-context", extend_html_context) diff --git a/sphinx_rtd_theme/layout.html b/sphinx_rtd_theme/layout.html index 115eed287..042070330 100644 --- a/sphinx_rtd_theme/layout.html +++ b/sphinx_rtd_theme/layout.html @@ -14,7 +14,7 @@ {%- set sphinx_version_info = (_ver_major, _ver_minor, -1) -%} - += (7, 2) %} data-content_root="{{ content_root }}"{% endif %}> {{- metatags }} @@ -28,16 +28,17 @@ {%- endif %} - {%- for css in css_files %} - {%- if css|attr("rel") %} - + {%- for css_file in css_files %} + {%- if css_file|attr("filename") %} + {{ css_tag(css_file) }} {%- else %} - + {%- endif %} {%- endfor %} - {%- for cssfile in extra_css_files %} - + {# "extra_css_files" is a theme option and it's always a string #} + {%- for css_file in extra_css_files %} + {%- endfor -%} {#- FAVICON diff --git a/tox.ini b/tox.ini index 3c435820e..0157a8f42 100644 --- a/tox.ini +++ b/tox.ini @@ -1,14 +1,10 @@ [tox] envlist = - # Python 2.7 support was removed in Sphinx 2 - py{27}-sphinx{17,18}{-html4,-html5,}{-qa,} - py{36,37,38,39}-sphinx{18,20,21,22,23,24,30,31,32,33,34,35,40,41,42,43,44,45,50,51,52}{-html4,-html5,}{-qa,} - # Python 3.10 working from Sphinx 4.2 and up - py{310}-sphinx{42,43,44,45,50,51,52,53,latest}{-html4,-html5}{-qa,} - # Sphinx 6+ has simplified docutils and Python support - py{38,39,10}-sphinx{60,61,70,71}{-html5,}{-qa,} + py{36,37,38,39,310}-sphinx{50,51,52,53}{-qa} + py{38,39,310}-sphinx{60,61,62,70,71}{-qa} + py{39,310}-sphinx{72,latest,dev}{-qa} # Python 3.11 working from Sphinx 5.3 and up - py{311}-sphinx{53,60,61,70,71,latest}{html5}{-qa,} + py{311}-sphinx{53,60,61,62,70,71,72,latest,dev}{-qa} [testenv] setenv = @@ -17,44 +13,21 @@ deps = . readthedocs-sphinx-ext pytest - sphinx17: Sphinx>=1.7,<1.8 - sphinx18: Sphinx>=1.8,<1.9 - sphinx20: Sphinx>=2.0,<2.1 - sphinx21: Sphinx>=2.1,<2.2 - sphinx22: Sphinx>=2.2,<2.3 - sphinx23: Sphinx>=2.3,<2.4 - sphinx24: Sphinx>=2.4,<2.5 - sphinx30: Sphinx>=3.0,<3.1 - sphinx31: Sphinx>=3.1,<3.2 - sphinx32: Sphinx>=3.2,<3.3 - sphinx33: Sphinx>=3.3,<3.4 - sphinx34: Sphinx>=3.4,<3.5 - sphinx35: Sphinx>=3.5,<3.6 - sphinx40: Sphinx>=4.0,<4.1 - sphinx41: Sphinx>=4.1,<4.2 - sphinx42: Sphinx>=4.2,<4.3 - sphinx43: Sphinx>=4.3,<4.4 - sphinx44: Sphinx>=4.4,<4.5 - sphinx45: Sphinx>=4.5,<4.6 sphinx50: Sphinx>=5.0,<5.1 sphinx51: Sphinx>=5.1,<5.2 sphinx52: Sphinx>=5.2,<5.3 sphinx53: Sphinx>=5.3,<5.4 sphinx60: Sphinx>=6.0,<6.1 sphinx61: Sphinx>=6.1,<6.2 + sphinx62: Sphinx>=6.2,<6.3 sphinx70: Sphinx>=7.0,<7.1 sphinx71: Sphinx>=7.1,<7.2 - # All these Sphinx versions actually break since docutils 0.18, so we need to add this upper bound - # Projects using these Sphinx versions will have to do the same - # See: https://github.com/readthedocs/sphinx_rtd_theme/pull/1304 - sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40,41,42}: docutils<0.18 - # External environments are required to add this dependency for older versions of Sphinx - # because it didn't ship with this upper bound. - # See: https://github.com/sphinx-doc/sphinx/issues/10291 - sphinx{17,18,20,21,22,23,24,30,31,32,33,34,35,40}: Jinja2<3.1 + sphinx72: Sphinx>=7.2,<7.3 sphinxlatest: Sphinx - sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip + dev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip +allowlist_externals = + echo commands = pytest {posargs} tests/ - !html4: sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html - html4: sphinx-build -b html -Dhtml4_writer=1 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html + sphinx-build -b html -Dhtml4_writer=0 -d {envtmpdir}/doctrees docs/ {envtmpdir}/html + echo "Open the following URL for visual testing: file://{envtmpdir}/html/demo/demo.html"