diff --git a/.github/workflows/check_install.yml b/.github/workflows/check_install.yml new file mode 100644 index 0000000..f3465f7 --- /dev/null +++ b/.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" diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index ffacb35..fa71235 100644 --- a/.github/workflows/documentation.yml +++ b/.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 diff --git a/.github/workflows/mint-release.yml b/.github/workflows/mint-release.yml index 8987170..1270d7f 100644 --- a/.github/workflows/mint-release.yml +++ b/.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: diff --git a/docs/conf.py b/docs/conf.py index db66c46..ad93567 100644 --- a/docs/conf.py +++ b/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 ---------------------------------------------- diff --git a/plasmapy_sphinx/__init__.py b/plasmapy_sphinx/__init__.py index d386675..cdefa04 100644 --- a/plasmapy_sphinx/__init__.py +++ b/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 diff --git a/plasmapy_sphinx/autodoc/automodapi.py b/plasmapy_sphinx/autodoc/automodapi.py index 65dd9eb..77a981d 100644 --- a/plasmapy_sphinx/autodoc/automodapi.py +++ b/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]]]: """ diff --git a/plasmapy_sphinx/automodsumm/core.py b/plasmapy_sphinx/automodsumm/core.py index 7998539..1090b8e 100644 --- a/plasmapy_sphinx/automodsumm/core.py +++ b/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"): diff --git a/plasmapy_sphinx/automodsumm/generate.py b/plasmapy_sphinx/automodsumm/generate.py index ddefba3..86314f6 100644 --- a/plasmapy_sphinx/automodsumm/generate.py +++ b/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): diff --git a/pyproject.toml b/pyproject.toml index 4fe0982..b5f0b06 100644 --- a/pyproject.toml +++ b/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", diff --git a/requirements/build.txt b/requirements/build.txt index cd42bfc..0c51567 100644 --- a/requirements/build.txt +++ b/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 diff --git a/requirements/docs.txt b/requirements/docs.txt index 62b1242..2947742 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -6,6 +6,7 @@ numpydoc packaging pillow +plasmapy > 8.0 pygments >= 2.11.0 sphinx-changelog sphinx-copybutton diff --git a/requirements/install.txt b/requirements/install.txt index d9e0af6..4c3126f 100644 --- a/requirements/install.txt +++ b/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