update to sphinx theme master 2.0.0

* 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> Release 2.0.0rc1 (readthedocs#1510) * Release 2.0.0rc1 * Update npm lock file Bump to next release 2.0.0rc2 (readthedocs#1511) Docs: Remove "git install" method from instructions (readthedocs#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 <humitos@gmail.com> Visual test with Firefox and tox (readthedocs#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 readthedocs#1388 Closes readthedocs#1388 * Default value for `DISPLAY` and `--new-tab` * Simplify the idea :) Remove Python2 leftovers (readthedocs#1514) Docs: update Read the Docs config (readthedocs#1518) Use the latest config file style. Set data-content_root for Sphinx ≥ 7.2 (readthedocs#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 <humitos@gmail.com> Use `css_tag` helper to inject CSS files (readthedocs#1519) * Use `css_tag` helper to inject CSS files * Typo Add support for `docutils==0.20.x` (readthedocs#1517) Closes readthedocs#1516 Release 2.0rc2 (readthedocs#1520) Version bump for 2.0rc3 development (readthedocs#1521) Next development version is 2.0rc3 for now, but more likely 2.1rc1 Fix readthedocs#1522: fix `'str' object has no attribute 'attributes'` (readthedocs#1528) * Fix readthedocs#1522: fix attribute error if css is str * Revert "Fix readthedocs#1522: fix attribute error if css is str" This reverts commit b22a77f. * 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 <humitos@gmail.com> Co-authored-by: Anthony Johnson <aj@ohess.org> Release 2.0.0rc3 (readthedocs#1535) Increment for next potential release (readthedocs#1536) Fix AttributeError when one of `css_files` is a string (readthedocs#1537) Fix AttributeError when one of css_files is a string Release 2.0.0rc4 (readthedocs#1538) Bump for next potential release, 2.0.0rc5 (readthedocs#1539) Release 2.0 final (readthedocs#1544)
ArduPilot · Jul 15, 2024 · f2bbe7d · f2bbe7d
1 parent e33fa17
commit f2bbe7d
Show file tree

Hide file tree

Showing 15 changed files with 150 additions and 328 deletions.
diff --git 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 "<<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
diff --git 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
@@ -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
@@ -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
@@ -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