[cleanup] Tox 4 compatibility and misc. CI fixes (#190)

Restore CI functionality and misc related cosmetic changes. - Fix tox 4 compatibility issue (`passenv` needs multiple lines). - Thanks @njzjz (cherry-picks #189)! - Loosen sphinx version packaging requirements (allow up to sphinx 6.x) - Thanks @renefritze (cherry-picks #179)! - Fix outdated bs4 intersphinx mapping (thanks @florianhumblot)! - Fix linkcheck redirect urls (primarily: `http` => `https`). - Expand python testing matrix to include python 3.11. - Windows CI: doxygen 1.8.6 => 1.9.6. - Expanded sphinx version testing to include all supported major versions. - Add PR autocancel (`concurrency`) and fail-fast to save time on CI.
svenevs · Mar 29, 2023 · e22b4f1 · e22b4f1
1 parent ebad897
commit e22b4f1
Show file tree

Hide file tree

Showing 28 changed files with 149 additions and 71 deletions.
diff --git a/.github/workflows/test_extras.yaml b/.github/workflows/test_extras.yaml
@@ -8,6 +8,11 @@ on:
  branches:
  - master
 
+# Cancel previous CI runs when new commits are added to a PR.
+concurrency:
+ group: ${{ github.head_ref || github.run_id }}-extras
+ cancel-in-progress: true
+
 jobs:
  build_docs_linkcheck:
  name: Docs / Linkcheck

diff --git a/.github/workflows/test_python.yaml b/.github/workflows/test_python.yaml
@@ -8,18 +8,25 @@ on:
  branches:
  - master
 
+# Cancel previous CI runs when new commits are added to a PR.
+concurrency:
+ group: ${{ github.head_ref || github.run_id }}-python
+ cancel-in-progress: true
+
 jobs:
  build:
+ # NOTE: runner strategy is to split across os and python version, but test multiple
+ # sphinx versions on a single runner. So do not add a matrix.sphinx-version.
  name: ${{ matrix.os }} / ${{ matrix.python-version }}
  runs-on: ${{ matrix.os }}
  strategy:
- fail-fast: false
+ fail-fast: true
  matrix:
  os: [macos-latest, ubuntu-latest, windows-latest]
- python-version: ['3.7', '3.8', '3.9', '3.10']
+ python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
  steps:
  - uses: actions/checkout@v2
- ##########################################################################
+ ##################################################################################
  - name: Install Doxygen (macOS)
  if: contains(matrix.os, 'macos')
  run: |
@@ -31,43 +38,92 @@ jobs:
  - name: Install Doxygen (Windows)
  if: contains(matrix.os, 'windows')
  run: |
- choco install doxygen.install --version 1.8.20
- echo "C:\Program Files\doxygen\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
- ##########################################################################
+ # This command has been failing with source forge mirror issues
+ # choco install doxygen.install --version 1.9.6
+ #
+ # https://github.com/actions/runner-images/issues/92#issuecomment-1172456433
+ $url = "https://www.doxygen.nl/files/doxygen-1.9.6.windows.x64.bin.zip"
+ Start-DownloadWithRetry -Url $url -Name "doxygen.zip" -DownloadPath "C:\"
+ Extract-7Zip -Path "C:\doxygen.zip" -DestinationPath "C:\Program Files\doxygen"
+ # Extracts to C:\Program Files\doxygen
+ # - doxygen.exe
+ # - doxyindexer.exe
+ # - doxysearch.cgi.exe
+ # - doxywizard.exe
+ # - libclang.dll
+ echo "C:\Program Files\doxygen" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+ ##################################################################################
  - name: Doxygen Version Dump
  run: doxygen --version
- ##########################################################################
+ ##################################################################################
  - name: Use Python ${{ matrix.python-version }}
  uses: actions/setup-python@v2
  with:
  python-version: ${{ matrix.python-version }}
  - name: Install Python Tools
  run: |
- pip install -U tox codecov coverage
+ pip install -U pip tox codecov coverage
+ # Sphinx 3.0.0 ###################################################################
  - name: Test Python ${{ matrix.python-version }} / sphinx==3.0.0
  env:
- # NOTE: in the future, we may want to use a larger matrix with more
- # combinations of sphinx and breathe, but for now it is not necessary.
+ # NOTE: this is the current minimum supported.
  SPHINX_VERSION: '==3.0.0'
  run: |
  tox -e py -- --cov-report xml:coverage.xml --cov
  - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx==3.0.0
  run: |
  codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx3.0.0"
  # Don't let code coverage utilities share anything, force clean it all.
- - name: Cleanup Python ${{ matrix.python-version }} / sphinx==3.0.0 Artifacts
+ - name: Cleanup Python ${{ matrix.python-version }} Testing / Coverage Artifacts
  run: |
  mv .gitignore nolongerignored
  git clean -n
  git clean -f
  git reset --hard
+ # Sphinx 4.x #####################################################################
  - name: Test Python ${{ matrix.python-version }} / sphinx 4.x
  env:
- # NOTE: in the future, we may want to use a larger matrix with more
- # combinations of sphinx and breathe, but for now it is not necessary.
- SPHINX_VERSION: '>=4<5'
+ # Test sphinx 4.x.
+ SPHINX_VERSION: '>=4,<5'
  run: |
  tox -e py -- --cov-report xml:coverage.xml --cov
  - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx 4.x
  run: |
  codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx4.x"
+ # Don't let code coverage utilities share anything, force clean it all.
+ - name: Cleanup Python ${{ matrix.python-version }} Testing / Coverage Artifacts
+ run: |
+ mv .gitignore nolongerignored
+ git clean -n
+ git clean -f
+ git reset --hard
+ # Sphinx 5.x #####################################################################
+ - name: Test Python ${{ matrix.python-version }} / sphinx 5.x
+ env:
+ # Test sphinx 5.x.
+ SPHINX_VERSION: '>=5,<6'
+ run: |
+ tox -e py -- --cov-report xml:coverage.xml --cov
+ - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx 5.x
+ run: |
+ codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx5.x"
+ # Don't let code coverage utilities share anything, force clean it all.
+ - name: Cleanup Python ${{ matrix.python-version }} Testing / Coverage Artifacts
+ run: |
+ mv .gitignore nolongerignored
+ git clean -n
+ git clean -f
+ git reset --hard
+ # Sphinx 6.x #####################################################################
+ - name: Test Python ${{ matrix.python-version }} / sphinx 6.x
+ # sphinx 6.x requires python 3.8+
+ if: ${{ matrix.python-version != '3.7' }}
+ env:
+ # Test sphinx 6.x.
+ SPHINX_VERSION: '>=6,<7'
+ run: |
+ tox -e py -- --cov-report xml:coverage.xml --cov
+ - name: Upload Code Coverage for Python ${{ matrix.python-version }} / sphinx 6.x
+ if: ${{ matrix.python-version != '3.7' }}
+ run: |
+ codecov --required -X gcov -f coverage.xml --name "[GHA] ${{ matrix.os }}-py${{ matrix.python-version }}-sphinx6.x"
diff --git a/.github/workflows/testing_projects.yaml b/.github/workflows/testing_projects.yaml
@@ -8,6 +8,11 @@ on:
  branches:
  - master
 
+# Cancel previous CI runs when new commits are added to a PR.
+concurrency:
+ group: ${{ github.head_ref || github.run_id }}-projects
+ cancel-in-progress: true
+
 jobs:
  build_linux:
  name: Linux

diff --git a/README.rst b/README.rst
@@ -51,7 +51,7 @@ everything started.
 **Why not use it?**
  It may be more involved than you need. Check out the ``breathe-apidoc`` tool that
  comes with your installation of ``breathe``. It is quite similar to the
- `Sphinx API doc tool <http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html>`_,
+ `Sphinx API doc tool <https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html>`_,
  and that may be all you are looking for to get your documentation displayed.
 
  If you are working with a small enough framework, you may also be satisfied with
@@ -92,18 +92,18 @@ HTML Theme choices:
 
 .. _companion: https://github.com/svenevs/exhale-companion
 
-.. _rtd: http://sphinx-rtd-theme.readthedocs.io/en/latest/
+.. _rtd: https://sphinx-rtd-theme.readthedocs.io/en/latest/
 .. _bstrap: https://ryan-roemer.github.io/sphinx-bootstrap-theme/
-.. _alabaster: http://alabaster.readthedocs.io/en/latest/
+.. _alabaster: https://alabaster.readthedocs.io/en/latest
 
 .. |rtd-docs| image:: https://readthedocs.org/projects/my-favorite-documentation-test/badge/?version=latest
- :target: http://my-favorite-documentation-test.readthedocs.io/en/latest/
+ :target: https://my-favorite-documentation-test.readthedocs.io/en/latest/
 
 .. |bootstrap-docs| image:: https://readthedocs.org/projects/my-favorite-documentation-test/badge/?version=bootstrap
- :target: http://my-favorite-documentation-test.readthedocs.io/en/bootstrap
+ :target: https://my-favorite-documentation-test.readthedocs.io/en/bootstrap
 
 .. |alabaster-docs| image:: https://readthedocs.org/projects/my-favorite-documentation-test/badge/?version=alabaster
- :target: http://my-favorite-documentation-test.readthedocs.io/en/alabaster
+ :target: https://my-favorite-documentation-test.readthedocs.io/en/alabaster
 
 
 Installation
@@ -115,10 +115,10 @@ generated Doxygen XML documentation. Exhale is `hosted on PyPI
 <https://pypi.org/project/exhale/>`_, meaning you can install it through the normal
 mechanisms, e.g.,
 
-__ http://www.sphinx-doc.org/en/stable/extensions.html
+__ https://www.sphinx-doc.org/en/master/usage/extensions/index.html
 
 .. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
-.. _lxml: http://lxml.de/
+.. _lxml: https://lxml.de/
 .. _Breathe: https://breathe.readthedocs.io/en/latest/
 
 .. code-block:: console
@@ -177,7 +177,7 @@ license:
 
 1. For non-bootstrap, I used Kate Morley's excellent and lightweight collapsibleLists_
  including the sample CSS / images on that post. She includes a generous
- `CC0 1.0 license <http://code.iamkate.com/>`_ for these files, as well as the rest of
+ `CC0 1.0 license <https://iamkate.com/code/>`_ for these files, as well as the rest of
  her website.
 
  For every HTML Theme I have tried, except for ones using bootstrap, this library
@@ -195,7 +195,7 @@ license:
 Both of these libraries and copies of their licenses can be found in the
 `data folder of the source code <https://github.com/svenevs/exhale/tree/master/exhale/data>`_.
 
-.. _collapsibleLists: http://code.iamkate.com/javascript/collapsible-lists/
+.. _collapsibleLists: https://iamkate.com/code/tree-views/
 
 __ https://github.com/jonmiles/bootstrap-treeview
 

diff --git a/docs/_extensions/autotested.py b/docs/_extensions/autotested.py
@@ -7,7 +7,7 @@
 # attribution. The CC0 1.0 license is chosen in the event that you need a license. #
 # #
 # Note that this code is basically just a bad modification of the Sphinx tutorial: #
-# http://www.sphinx-doc.org/en/latest/extdev/tutorial.html  #
+# https://www.sphinx-doc.org/en/latest/extdev/tutorial.html #
 ########################################################################################
 import re
 import textwrap

diff --git a/docs/_extensions/exhaleversion.py b/docs/_extensions/exhaleversion.py
@@ -7,7 +7,7 @@
 # attribution. The CC0 1.0 license is chosen in the event that you need a license. #
 # #
 # Note that this code is basically just a bad modification of the Sphinx tutorial: #
-# http://www.sphinx-doc.org/en/latest/extdev/tutorial.html  #
+# https://www.sphinx-doc.org/en/latest/extdev/tutorial.html #
 ########################################################################################
 import re
 import textwrap

diff --git a/docs/_intersphinx/README.md b/docs/_intersphinx/README.md
@@ -14,7 +14,7 @@ Use the tool `sphobjinv` to do this (`pip install sphobjinv`).
 
 - [Explanation of syntax][syntax].
 
-[syntax]: http://sphinx-objectsinv-encoderdecoder.readthedocs.io/en/latest/syntax.html
+[syntax]: https://sphinx-objectsinv-encoderdecoder.readthedocs.io/en/latest/syntax.html
 
 ## How to Reproduce
 

diff --git a/docs/_intersphinx/bs4_objects.inv b/docs/_intersphinx/bs4_objects.inv
diff --git a/docs/_intersphinx/bs4_objects.txt b/docs/_intersphinx/bs4_objects.txt
@@ -5,7 +5,7 @@
 
 bs4.BeautifulSoup py:class 1 index.html#beautifulsoup -
 bs4.BeautifulSoup.get_text py:method 1 index.html#get-text -
-bs4.element.Tag py:class 1 index.html#tag -
+bs4.element.Tag py:class 1 index.html#bs4.Tag -
 
 
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -69,8 +69,8 @@
 
 # -- Intersphinx Extension Configuration -----------------------------------------------
 intersphinx_mapping = {
- "python": ("http://docs.python.org/", None),
- "sphinx": ("http://www.sphinx-doc.org/en/master", None),
+ "python": ("https://docs.python.org/", None),
+ "sphinx": ("https://www.sphinx-doc.org/en/master", None),
  "pytest": ("https://docs.pytest.org/en/latest/", None),
  # See _intersphinx/README.md
  "bs4": (

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -18,7 +18,7 @@ to this FAQ.
 Make sure you set the :data:`~exhale.configs.verboseBuild` to ``True``, there may be some
 useful information being printed there.
 
-.. _companion: http://my-favorite-documentation-test.readthedocs.io/en/latest/
+.. _companion: https://my-favorite-documentation-test.readthedocs.io/en/latest/
 
 Can I use the formidable Intersphinx extension?
 ----------------------------------------------------------------------------------------
@@ -27,7 +27,7 @@ Heck yes! This has almost nothing to do with Exhale, and everything to do with
 I've prepared a crash-course on how to get it up and running on the companion site's
 `Using Intersphinx <using_intersphinx_>`_ page.
 
-.. _using_intersphinx: http://my-favorite-documentation-test.readthedocs.io/en/latest/using_intersphinx.html
+.. _using_intersphinx: https://my-favorite-documentation-test.readthedocs.io/en/latest/using_intersphinx.html
 
 Why does it build locally, but not on Read the Docs?
 ----------------------------------------------------------------------------------------

diff --git a/docs/mastering_doxygen.rst b/docs/mastering_doxygen.rst
@@ -20,7 +20,7 @@ What is Doxygen, and How do I Approach it?
 `Doxygen`__ is a documentation (doxy) generation (gen) system. You should approach it
 with fear, awe, and humility. And remember to never look it in the eyes.
 
-__ http://www.doxygen.nl/
+__ https://www.doxygen.nl/
 
 Doxygen on its own is a fascinating tool. It's stupendously flexible, and immensely
 powerful. I mean let's think about what it's actually doing: it's parsing and
@@ -68,7 +68,7 @@ overwhelming) approach of just reading the entire generated ``Doxyfile``. You c
 acquire a shiny new ``Doxyfile`` by executing ``doxygen -g`` in your terminal in a
 directory where there is no ``Doxyfile`` present.
 
-__ http://www.doxygen.nl/manual/index.html
+__ https://www.doxygen.nl/manual/index.html
 
 .. tip::
 
@@ -268,7 +268,7 @@ Additional Variables with Important Impacts
  PREDEFINED += NAMESPACE_BEGIN(nanogui)="namespace nanogui {"
  PREDEFINED += NAMESPACE_END(nanogui)="}"
 
- __ http://nanogui.readthedocs.io/en/latest/
+ __ https://nanogui.readthedocs.io/en/latest/
 
 Adding Documentation to the Code
 ****************************************************************************************
@@ -321,7 +321,7 @@ documenting specific aspects:
 | ``\c`` | Teletype a single word (e.g. ``\c computeroutput``). |
 +-----------------+--------------------------------------------------------------------+
 
-__ http://www.doxygen.nl/manual/docblocks.html
+__ https://www.doxygen.nl/manual/docblocks.html
 
 Doxygen Documentation Pitfalls
 ----------------------------------------------------------------------------------------
@@ -342,7 +342,7 @@ documentation is empty)! From the Doxygen documentation reiteration_:
  (functions, typedefs, enum, macros, etc), you must document the file in which they
  are defined.
 
-.. _reiteration: http://www.doxygen.nl/manual/docblocks.html
+.. _reiteration: https://www.doxygen.nl/manual/docblocks.html
 
 .. _file_associations:
 
@@ -383,7 +383,7 @@ might look like:
  thing() {}
  };
 
-.. _FAQ: http://www.doxygen.nl/manual/faq.html#faq_code_inc
+.. _FAQ: https://www.doxygen.nl/manual/faq.html#faq_code_inc
 
 Features Available by Using Sphinx / Breathe / Exhale by way of reStructuredText
 ----------------------------------------------------------------------------------------
@@ -420,7 +420,7 @@ Listings
 
 See the `official documentation`__.
 
-__ http://docutils.sourceforge.net/docs/user/rst/quickref.html#bullet-lists
+__ https://docutils.sourceforge.io/docs/user/rst/quickref.html#bullet-lists
 
 Tables
 ****************************************************************************************
@@ -432,15 +432,15 @@ Tables
 
 Use `grid tables`__!!!
 
-__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#grid-tables
+__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
 
 Hyperlinks
 ****************************************************************************************
 
 I'll confess that reStructuredText hyperlinks are probably the most confusing. Best to
 leave the explaining to the `official documentation`__.
 
-__ http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets
+__ https://docutils.sourceforge.io/docs/user/rst/quickref.html#hyperlink-targets
 
 Useful Directives
 ****************************************************************************************

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -87,7 +87,7 @@ but:
  Where you would store custom jinja2 templates to override settings in your chosen
  :confval:`sphinx:html_theme`. The templates are read from
  :confval:`sphinx:templates_path` which defaults to ``_templates``. See also:
- `Sphinx Templating <https://www.sphinx-doc.org/en/master/templating.html>`_.
+ `Sphinx Templating <https://www.sphinx-doc.org/en/master/development/templating.html>`_.
 
 
 Finishing the ``sphinx-quickstart`` command output, we enter the relevant metadata about