mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
2.0 milestone: drop supported versions (#1500)
* 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 <aj@ohess.org>
This commit is contained in:
Manuel Kaufmann
GitHub
parent
15ed4de08d
commit
0e7b28ad4a
@ -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 "<<parameters.version>>-sphinx{<<parameters.sphinx-version>>}"
|
||||
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
|
||||
|
||||
@ -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
|
||||
============
|
||||
|
||||
@ -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 <https://endoflife.date/internet-explorer>`_,
|
||||
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.
|
||||
|
||||
@ -19,7 +19,7 @@ project_urls =
|
||||
Homepage = https://sphinx-rtd-theme.readthedocs.io/
|
||||
Source Code = https://github.com/readthedocs/sphinx_rtd_theme
|
||||
Issue Tracker = https://github.com/readthedocs/sphinx_rtd_theme/issues
|
||||
classifiers =
|
||||
classifiers =
|
||||
Framework :: Sphinx
|
||||
Framework :: Sphinx :: Theme
|
||||
Development Status :: 5 - Production/Stable
|
||||
@ -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,9 +43,9 @@ 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
|
||||
sphinx >=5,<8
|
||||
docutils <0.19
|
||||
sphinxcontrib-jquery >=4,<5
|
||||
tests_require =
|
||||
|
||||
@ -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)
|
||||
|
||||
46
tox.ini
46
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,18 @@ 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
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user