IntenseWebs/sphinx_rtd_theme
3
0
Fork 0
mirror of https://github.com/readthedocs/sphinx_rtd_theme.git synced 2025-02-25 18:55:21 -06:00
Code Issues Packages Projects Releases Wiki Activity

Prepare for 3.0 release (#1576)

Browse Source 
* Tests: `sphinxdev` tox environment installs Sphinx from `master`

It seems we had a bug in the name and it wasn't installing Sphinx from `master`.
I expect this test to fail now because we pin `Sphinx<8`, but that's fine for now.

* Prepare for 3.0 release

- Drop Python <3.8
- Drop docutils <=0.18
- Add support for docutils 0.21
- Add support for Python 3.12

This follows the plan we wrote in
https://sphinx-rtd-theme.readthedocs.io/en/stable/development.html#roadmap-release-3-0-0

The main idea here is to move forward with newer versions and drop support for
old stuffs so we reduce the maintanence burden.

* Update CircleCI matrix

* More fixes to CircleCI

* Run test over Sphinx 8.0

* Update contributing guide

* Remove deprecated `readthedocs-sphinx-ext`

* Remove old Sphinx versions

* Uninstall our extension

* Show a warning if `extra_css_files` is in the `html_context`

See https://github.com/readthedocs/sphinx_rtd_theme/pull/450

* Update development page

* Add deprecate warning for `analytics_` theme options

* Update docs

* Remove unused dependency

Closes #1533

* Remove environment variables from our docs

This was already added in a more generic way to the theme itself.

* Require Sphinx >=6.0

* Deprecation warning about `get_html_theme_path`

See https://github.com/readthedocs/sphinx_rtd_theme/pull/1479#issuecomment-2296317034
This commit is contained in:
Manuel Kaufmann 2024-08-20 13:18:34 +02:00 committed by GitHub
parent 768dcc1467
commit 6b587d1c67
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 75 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
.circleci/config.yml
View File

@ -44,54 +44,51 @@ jobs:
- image: 'cimg/python:3.9-node'
steps:
- run-build: {}
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: "50,51,52,53,60,61,62,70,71,latest"
sphinx-version: "60,61,62,70,71"
py39:
docker:
- image: 'cimg/python:3.9'
steps:
- run-tox:
version: py39
sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest"
sphinx-version: "60,61,62,70,71,72,73,74"
py310:
docker:
- image: 'cimg/python:3.10'
steps:
- run-tox:
version: py310
sphinx-version: "50,51,52,53,60,61,62,70,71,72,latest"
sphinx-version: "60,61,62,70,71,72,73,74,80,latest,dev"
py311:
docker:
- image: 'cimg/python:3.11'
steps:
- run-tox:
version: py311
sphinx-version: "53,60,61,62,70,71,72,latest,dev"
sphinx-version: "72,73,74,80,latest,dev"
py312:
docker:
- image: 'cimg/python:3.12'
steps:
- run-tox:
version: py312
sphinx-version: "72,73,74,80,latest,dev"
workflows:
version: 2
tests:
jobs:
- build
- py312:
requires:
- build
- py311:
requires:
- build
@ -104,9 +101,3 @@ workflows:
- py38:
requires:
- build
- py37:
requires:
- build
- py36:
requires:
- build

4
docs/conf.py
View File

@ -68,10 +68,6 @@ if not 'READTHEDOCS' in os.environ:
range(1, 100)
))
if 'READTHEDOCS' in os.environ:
html_context['READTHEDOCS'] = True
html_context['READTHEDOCS_PROJECT'] = os.environ.get("READTHEDOCS_PROJECT")
html_logo = "demo/static/logo-wordmark-light.svg"
html_show_sourcelink = True
html_favicon = "demo/static/favicon.ico"

7
docs/configuring.rst
View File

@ -102,7 +102,11 @@ Miscellaneous options
:type: string
.. deprecated:: 3.0.0
The ``analytics_id`` option is deprecated, use the sphinxcontrib-googleanalytics_ extension instead.
.. _gtag.js: https://developers.google.com/gtagjs
.. _sphinxcontrib-googleanalytics: https://pypi.org/project/sphinxcontrib-googleanalytics/
.. confval:: analytics_anonymize_ip
@ -111,6 +115,9 @@ Miscellaneous options
:type: boolean
:default: ``False``
.. deprecated:: 3.0.0
The ``analytics_anonymize_ip`` option is deprecated, use the sphinxcontrib-googleanalytics_ extension instead.
.. confval:: canonical_url
This will specify a `canonical URL`_ meta link element to tell search

28
docs/contributing.rst
View File

@ -86,7 +86,7 @@ Use the following steps:
# Runs the development webserver
$ docker-compose run sphinx_rtd_theme dev
# If you want to copy stuff out of the Docker environment, run this make
# target or read the actual Makefile to see what is going on.
# We suggest running this command every time that you want to quickly build
@ -108,13 +108,13 @@ The following cases need to be tested with changes to CSS or JavaScript:
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``
We currently support Sphinx ``>=6.0``
It's easiest to test combinations of dependency versions using ``tox``:
.. code:: console
% tox -e py310-sphinx62
% tox -e py312-sphinx74
If the tests and build are successful, you can view the built documentation at
the directory noted by Sphinx:
@ -123,9 +123,9 @@ the directory noted by Sphinx:
build succeeded, 10 warnings.
The HTML pages are in .tox/py310-sphinx62/tmp/html.
The HTML pages are in .tox/py312-sphinx74/tmp/html.
___________________________ summary ___________________________
py310-sphinx62: commands succeeded
py312-sphinx74: commands succeeded
congratulations :)
You can then open up this path with a series of browsers to test.
@ -135,12 +135,12 @@ multiple ``tox`` environments, and open both up for comparison:
.. code:: console
% tox -e py310-sphinx62
% tox -e py312-sphinx62
...
% tox -e py310-sphinx53
% tox -e py312-sphinx74
...
% firefox .tox/py310-sphinx62/tmp/html/index.html
% firefox .tox/py310-sphinx53/tmp/html/index.html
% firefox .tox/py312-sphinx62/tmp/html/index.html
% firefox .tox/py312-sphinx74/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
@ -167,11 +167,11 @@ Currently, the most important environments to QA are:
the cases above, we'll be here all day. Python 3, and latest
minor of each major Sphinx release should give us enough work.
* ``py310-sphinx53``
* ``py310-sphinx62``
* ``py310-sphinx72``
* ``py310-sphinxlatest``
* ``py310-sphinxdev``
* ``py312-sphinx62``
* ``py312-sphinx74``
* ``py312-sphinx80``
* ``py312-sphinxlatest``
* ``py312-sphinxdev``
Translations
============

24
docs/development.rst
View File

@ -36,13 +36,8 @@ combinations.
Unsupported browser/operating system combinations include:
Internet Explorer (any OS, versions <=10)
**Unsupported.** IE11 is the last partially supported version. We do no
testing on prior versions.
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-3.0.0` release.
Internet Explorer (any OS, any version)
Support was 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 +57,14 @@ The theme officially supports the following dependencies in your Sphinx project:
* - Dependency
- Versions
* - Python
- 3.6 or greater
- 3.8 or greater
* - Sphinx
- 5 or greater
- 6 or greater
* - docutils
- >= 0.14, < 0.19
- > 0.18, < 0.22
.. deprecated:: 3.0
Sphinx < 6 support removed
.. deprecated:: 2.0
Sphinx < 5 support removed
@ -179,10 +177,10 @@ HTML4 support will be removed
3.0.0
~~~~~
:Planned release date: 2024 Q1
:Planned release date: 2024 Q3
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.
This release will drop support for old Python and Sphinx versions,
and will add support for new ones.
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,

10
setup.cfg
View File

@ -29,12 +29,11 @@ classifiers =
Intended Audience :: Developers
Programming Language :: Python :: 3
Programming Language :: Python :: 3 :: Only
Programming Language :: Python :: 3.6
Programming Language :: Python :: 3.7
Programming Language :: Python :: 3.8
Programming Language :: Python :: 3.9
Programming Language :: Python :: 3.10
Programming Language :: Python :: 3.11
Programming Language :: Python :: 3.12
Operating System :: OS Independent
Topic :: Documentation
Topic :: Software Development :: Documentation
@ -43,10 +42,10 @@ classifiers =
include_package_data = True
zip_safe = False
packages = sphinx_rtd_theme
python_requires = >=3.6
python_requires = >=3.8
install_requires =
sphinx >=5,<8
docutils <0.21
sphinx >=6,<9
docutils >0.18,<0.22
sphinxcontrib-jquery >=4,<5
tests_require =
pytest
@ -54,7 +53,6 @@ tests_require =
[options.extras_require]
dev =
transifex-client
sphinxcontrib-httpdomain
bump2version
wheel
twine

21
sphinx_rtd_theme/__init__.py
View File

@ -21,6 +21,10 @@ logger = getLogger(__name__)
def get_html_theme_path():
"""Return list of HTML theme paths."""
logger.warning(
_('Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code.')
)
cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
return cur_dir
@ -32,6 +36,21 @@ def config_initiated(app, config):
_('The canonical_url option is deprecated, use the html_baseurl option from Sphinx instead.')
)
if theme_options.get("analytics_id"):
logger.warning(
_('The analytics_id option is deprecated, use the sphinxcontrib-googleanalytics extension instead.')
)
if theme_options.get("analytics_anonymize_ip"):
logger.warning(
_('The analytics_anonymize_ip option is deprecated, use the sphinxcontrib-googleanalytics extension instead.')
)
if "extra_css_files" in config.html_context:
logger.warning(
_('The extra_css_file option is deprecated, use the html_css_files option from Sphinx instead.')
)
def extend_html_context(app, pagename, templatename, context, doctree):
# Add ``sphinx_version_info`` tuple for use in Jinja templates
@ -52,7 +71,7 @@ def setup(app):
if python_version[0] < 3:
logger.error("Python 2 is not supported with sphinx_rtd_theme, update to Python 3.")
app.require_sphinx('5.0')
app.require_sphinx('6.0')
if app.config.html4_writer:
logger.error("'html4_writer' is not supported with sphinx_rtd_theme.")

4
tests/util.py
View File

@ -34,7 +34,6 @@ def build(root, builder='html', **kwargs):
confoverrides['html_theme'] = 'sphinx_rtd_theme'
extensions = confoverrides.get('extensions', [])
extensions.append('sphinx_rtd_theme')
extensions.append('readthedocs_ext.readthedocs')
confoverrides['extensions'] = extensions
kwargs['confoverrides'] = confoverrides
@ -55,7 +54,6 @@ def build(root, builder='html', **kwargs):
def build_all(root, **kwargs):
for builder in ['html', 'singlehtml', 'readthedocs', 'readthedocsdirhtml',
'readthedocssinglehtml', 'readthedocssinglehtmllocalmedia']:
for builder in ['html', 'singlehtml']:
with build(root, builder, **kwargs) as ret:
yield ret

12
tox.ini
View File

@ -1,28 +1,22 @@
[tox]
envlist =
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,62,70,71,72,latest,dev}{-qa}
py{39,310,311,312}-sphinx{72,73,74,80}{-qa}
py{310,311,312}-sphinx{latest,dev}{-qa}
[testenv]
setenv =
LANG=C
deps =
.
readthedocs-sphinx-ext
pytest
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
sphinx72: Sphinx>=7.2,<7.3
sphinx80: Sphinx>=8.0,<8.1
sphinxlatest: Sphinx
sphinxdev: https://github.com/sphinx-doc/sphinx/archive/refs/heads/master.zip
allowlist_externals =