"Modernize" GitHub Wrokflows (#18)

* put install and import test into its own workflow

* add tests on py 3.6 and 3.13

* cache tests and set fetch-depth to 1

* restrict workflow permissions

* no not explicitly install plasmapy

* set upper sphinx limit to < 8.2

* set upper sphinx limit to < 7.4

* add plasmapy dependency to the documentation requirements

* set min python version to 3.8

* set min setuptools version to 61

* remove fail on warnings and add 3x verbosity

* remove the 3x verbosity

* add dependency "packaging"

* adopt a kwarg passing scheme so we can be flexible in passing args to generate_autosummary_content(), who's signature changes for sphinx >= 8.0

* put sphinx upper limit to 8.2

* add sphinx_limits workflow

* repair sphinx_limits workflow

* repair sphinx_limits workflow

* replace double quotes with single quotes

* put ${{ matrix.sphinx }} between quotes

* put fail on warning for the sphinx_limit workflow

* put fail on warning for the documentation workflow

* explicitly pass prefixes to import_by_name

* explicitly remove prefixes before passing to parent method

* add a nitpick exception for SphinxDirective.parse_inline

* remove the quiet tag from sphinx builds workflow

* add to nitpick exceptions

* remove the string prefix in a python agnostic way

* correct the prefix removal +1

* add nitpick ignore for ObjectMembers type annotation

* make nitpick ignore rules a little more generic

* add ObjectMember to nitpick ignore rules

* remove upper dependency limit on sphinx

* add a build on py3.11

* add kwargs for generate_autosummary_content() that are specific to sphinx >= 8.2 specific

* remove trailing whitespace

* add check on py3.11

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* wrangle option :no-index: to :index: for sphinx < 7.2

* remove unused import

* remove wrongly placed handling of the no-index option for sphinx < 7.2

* add the 'no-index' option to option_spec if ModuleDocumenter.option_spec does not have it

* wrangle option :no-index: to :index: for sphinx < 7.2

* remove unused import

* remove unused import

* add permissions statement

* remove if-clause for importing importlib.metadata

* add build for sphinx<7.2

* update actions/setup-python@v4 to actions/setup-python@v5

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: rocco8773

.github/workflows/check_install.yml

@@ -0,0 +1,40 @@
+name: Install and Import
+
+on:
+  push:
+    branches:
+    - main
+    - v0.*.x
+    tags:
+    - v*
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}  # disables all GitHub permissions for the workflow
+
+jobs:
+  pip-install-and-import:
+    name: Installation with pip & import (py-${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.8', '3.10', '3.11', '3.12', '3.13']
+        os: [ubuntu-latest]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 1
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python }}
+        cache: pip
+    - name: Install plasmapy_sphinx with pip
+      run: pip install .
+    - name: Import plasmapy_sphinx
+      run: python -c "import plasmapy_sphinx"

.github/workflows/documentation.yml

@@ -10,6 +10,8 @@ on:
   pull_request:
   workflow_dispatch:
 
+permissions: {}  # disables all GitHub permissions for the workflow
+
 jobs:
   documentation:
     name: Doc Build - py${{ matrix.python }} on ${{ matrix.os }}
@@ -18,39 +20,64 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ['3.10', '3.12']
+        python: ['3.8', '3.10', '3.11', '3.12', '3.13']
         os: [ubuntu-latest]
 
     steps:
     - name: Checkout code
       uses: actions/checkout@v3
       with:
-        fetch-depth: 0
+        fetch-depth: 1
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python }}
+        cache: pip
     - name: Install dependencies
       run: |
         python -m pip install --progress-bar off --upgrade pip
-        python -m pip install --progress-bar off -r requirements/docs.txt git+https://github.com/PlasmaPy/plasmapy
+        python -m pip install --progress-bar off -r requirements/docs.txt
         sudo apt-get install graphviz pandoc
     - name: Build Docs
       run: |
-        sphinx-build ./docs ./docs/_build -n --keep-going -W -b html -q
+        sphinx-build ./docs ./docs/_build -n --keep-going -W -b html
+
+  sphinx_limits:
+    name: Doc Build on ${{ matrix.sphinx }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        include:
+        - python: '3.11'
+          os: ubuntu-latest
+          sphinx: sphinx<7.2
 
-  pip-install:
-    name: Installation with pip
-    runs-on: ubuntu-latest
+        - python: '3.12'
+          os: ubuntu-latest
+          sphinx: sphinx<7.4
+
+        - python: '3.12'
+          os: ubuntu-latest
+          sphinx: sphinx<8.2
 
     steps:
     - name: Checkout code
       uses: actions/checkout@v3
       with:
-        fetch-depth: 0
+        fetch-depth: 1
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.12
-    - name: Install plasmapy_sphinx with pip
-      run: pip install .
+        python-version: ${{ matrix.python }}
+        cache: pip
+    - name: Install dependencies
+      run: |
+        python -m pip install --progress-bar off --upgrade pip
+        python -m pip install --progress-bar off -r requirements/docs.txt "${{ matrix.sphinx }}"
+        sudo apt-get install graphviz pandoc
+    - name: Build Docs
+      run: |
+        sphinx-build ./docs ./docs/_build -n --keep-going -W -b html

.github/workflows/mint-release.yml

@@ -8,6 +8,8 @@ on:
         required: true
         default: 0.1.0rc1
 
+permissions: {}  # disables all GitHub permissions for the workflow
+
 jobs:
 
   tag:

docs/conf.py

@@ -339,6 +339,10 @@
     (python_role, "plasmapy.analysis.swept_langmuir.find_floating_potential"),
     (python_role, "plasmapy.particles.particle_collections"),
     (python_role, "plasmapy.utils.decorators.lite_func"),
+    # Sphinx
+    (python_role, "system_message"),  # sphinx.util.docutils.system_message
+    (python_role, "ObjectMember"),  # sphinx.ext.autodoc.ObjectMember
+    (python_role, "ObjectMembers"),  # sphinx.ext.autodoc.ObjectMembers
 ]
 
 # -- Options for HTML output ----------------------------------------------

plasmapy_sphinx/__init__.py

@@ -70,13 +70,10 @@
 # This is the same check as the one at the top of setup.py
 import sys
 
-if sys.version_info < (3, 6):  # coverage: ignore
-    raise ImportError("plasmapy_sphinx does not support Python < 3.6")
+if sys.version_info < (3, 8):  # coverage: ignore
+    raise ImportError("plasmapy_sphinx does not support Python < 3.8")
 
-if sys.version_info >= (3, 8):
-    from importlib.metadata import version, PackageNotFoundError
-else:
-    from importlib_metadata import version, PackageNotFoundError
+from importlib.metadata import version, PackageNotFoundError
 
 from plasmapy_sphinx import autodoc, automodsumm, directives, utils
 

plasmapy_sphinx/autodoc/automodapi.py

@@ -303,12 +303,13 @@
 
 import inspect
 import re
-import sys
 import warnings
 
 from collections import OrderedDict
 from docutils.parsers.rst import directives
 from docutils.statemachine import StringList
+from packaging.version import Version
+from sphinx import __version__ as sphinx_version
 from sphinx.application import Sphinx
 
 try:
@@ -349,6 +350,8 @@ class RemovedInSphinx50Warning(PendingDeprecationWarning):
     "inheritance-diagram": bool_option,
     "no-inheritance-diagram": bool_option,
 }  # type: Dict[str, Callable]
+if "no-index" not in _option_spec:
+    _option_spec["no-index"] = bool_option
 for option_name in list(_option_spec):
     if "member" in option_name:
         del _option_spec[option_name]
@@ -504,6 +507,15 @@ class ModAPIDocumenter(ModuleDocumenter):
         ),
     }
 
+    def __init__(self, *args: Any) -> None:
+        super().__init__(*args)
+
+        if Version(sphinx_version) < Version("7.2") and "no-index" in self.options:
+            # sphinx started using :no-index: instead of the original :noindex:
+            # in version 7.2
+            opt_value = self.options.pop("no-index")
+            self.options["noindex"] = opt_value
+
     @property
     def grouping_info(self) -> Dict[str, Dict[str, Union[str, None]]]:
         """

plasmapy_sphinx/automodsumm/core.py

@@ -208,6 +208,8 @@
 import os
 
 from importlib import import_module
+from packaging.version import Version
+from sphinx import __version__ as sphinx_version
 from sphinx.ext.autosummary import Autosummary
 from sphinx.util import logging
 from typing import Any, Callable, Dict, List, Tuple, Union
@@ -664,7 +666,16 @@ def import_by_name(
         self, name: str, prefixes: List[str]
     ) -> Tuple[str, Any, Any, str]:
         """See :func:`sphinx.ext.autosummary.import_by_name`"""
-        return super(Automodsumm, self).import_by_name(name, prefixes)
+
+        for prefix in prefixes:
+            if prefix is None:
+                continue
+
+            if name.startswith(f"{prefix}."):
+                name = name[len(prefix)+1:]
+                break
+
+        return super().import_by_name(name, prefixes)
 
 
 def setup(app: "Sphinx"):

plasmapy_sphinx/automodsumm/generate.py

@@ -8,6 +8,8 @@
 import re
 
 from jinja2 import TemplateNotFound
+from packaging.version import Version
+from sphinx import __version__ as sphinx_version
 from sphinx.ext.autodoc.mock import mock
 from sphinx.ext.autosummary import get_rst_suffix, import_by_name, import_ivar_by_name
 from sphinx.ext.autosummary.generate import (
@@ -25,7 +27,6 @@
 if False:
     # for annotation, does not need real import
     from sphinx.application import Sphinx
-    from sphinx.builders import Builder
 
 
 logger = logging.getLogger(__name__)
@@ -291,7 +292,7 @@ def generate_docs(
             ensuredir(path)
 
             try:
-                name, obj, parent, modname = import_by_name(entry.name)
+                name, obj, parent, modname = import_by_name(entry.name, prefixes=(None,))
                 qualname = name.replace(modname + ".", "")
             except ImportError as e:
                 try:
@@ -306,19 +307,26 @@ def generate_docs(
             if app:
                 context.update(app.config.autosummary_context)
 
-            content = generate_autosummary_content(
-                name,
-                obj,
-                parent,
-                template,
-                entry.template,
-                imported_members,
-                app,
-                entry.recursive,
-                context,
-                modname,
-                qualname,
-            )
+            _kwargs = {
+                "name": name,
+                "obj": obj,
+                "parent": parent,
+                "template": template,
+                "template_name": entry.template,
+                "imported_members": imported_members,
+                "recursive": entry.recursive,
+                "context": context,
+                "modname": modname,
+                "qualname": qualname,
+            }
+            if Version(sphinx_version) < Version("8.2"):
+                _kwargs["app"] = app
+            else:
+                _kwargs["config"] = app.config
+                _kwargs["events"] = app.events
+                _kwargs["registry"] = app.registry
+
+            content = generate_autosummary_content(**_kwargs)
 
             filename = os.path.join(path, filename_map.get(name, name) + suffix)
             if os.path.isfile(filename):

pyproject.toml

@@ -1,6 +1,6 @@
 [build-system]
 requires = [  # ought to mirror 'requirements/build.txt'
-    "setuptools >= 41.2",
+    "setuptools >= 61",
     "setuptools_scm",
     "wheel >= 0.29.0",
 ]
@@ -14,7 +14,7 @@ maintainers = [
 ]
 description = "Sphinx extensions for the PlasmaPy Project"
 readme = "README.md"
-requires-python = ">=3.6"
+requires-python = ">=3.8"
 dynamic = ["version"]
 license = {file = "LICENSE.md"}
 keywords = ["plasmapy", "sphinx", "documentation"]
@@ -24,8 +24,6 @@ classifiers = [
     "License :: OSI Approved :: BSD License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.6",
-    "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
@@ -37,6 +35,7 @@ dependencies = [  # ought to mirror 'requirements/install.txt'
   "docutils",
   "importlib_metadata; python_version < '3.8'",
   "jinja2 != 3.1",
+  "packaging",
   "sphinx >= 4.4",
   "sphinx-gallery",
   "sphinx_rtd_theme >= 1.0.0",
@@ -65,6 +64,7 @@ docs = [  # ought to mirror 'requirements/docs.txt'
     "numpydoc",
     "packaging",
     "pillow",
+    "plasmapy > 8.0",
     "pygments >= 2.11.0",
     "sphinx-changelog",
     "sphinx-copybutton",

requirements/build.txt

@@ -3,6 +3,6 @@
 #
 # ought to mirror [build-system.requires] under in pyproject.toml
 #
-setuptools >= 41.2
+setuptools >= 61
 setuptools_scm
 wheel >= 0.29.0

requirements/docs.txt

@@ -6,6 +6,7 @@
 numpydoc
 packaging
 pillow
+plasmapy > 8.0
 pygments >= 2.11.0
 sphinx-changelog
 sphinx-copybutton

requirements/install.txt

@@ -6,6 +6,7 @@
 docutils
 importlib_metadata; python_version < '3.8'
 jinja2 != 3.1
+packaging
 sphinx >= 4.4
 sphinx-gallery
 sphinx_rtd_theme >= 1.0.0