Merge branch 'main' into soft-sphinx

Author: rossbar

.github/workflows/main.yml

@@ -5,7 +5,7 @@ jobs:
     name: Run CircleCI artifacts redirector
     steps:
       - name: GitHub Action step
-        uses: scientific-python/circleci-artifacts-redirector-action@839631420e45a08af893032e5a5e8843bf47e8ff # v1.2.0
+        uses: scientific-python/circleci-artifacts-redirector-action@5d358ff96e96429a5c64a969bb4a574555439f4f # v1.3.1
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           api-token: ${{ secrets.CIRCLECI_ARTIFACT_REDIRECTOR_TOKEN }}

.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5.1.1
+      - uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0
         with:
           python-version: "3.12"
       - name: Build wheels
@@ -24,7 +24,7 @@ jobs:
           pip install -U build twine wheel
           python -m build --sdist --wheel
       - run: twine check --strict dist/*
-      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
         with:
           name: dist
           path: dist
@@ -40,8 +40,8 @@ jobs:
       # IMPORTANT: this permission is mandatory for trusted publishing
       id-token: write
     steps:
-      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
         with:
           name: dist
           path: dist
-      - uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

.github/workflows/test.yml

@@ -30,7 +30,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Python setup
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -83,7 +83,7 @@ jobs:
       - uses: actions/checkout@v5
 
       - name: Python setup
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 

numpydoc/docscrape_sphinx.py

@@ -37,7 +37,7 @@ def load_config(self, config):
             self.template = template_env.get_template("numpydoc_docstring.rst")
 
     # string conversion routines
-    def _str_header(self, name, symbol="`"):
+    def _str_header(self, name):
         return [".. rubric:: " + name, ""]
 
     def _str_field_list(self, name):

numpydoc/tests/hooks/test_utils.py

@@ -23,7 +23,10 @@ def test_find_project_root(tmp_path, request, reason_file, files, expected_reaso
         (tmp_path / reason_file).touch()
 
     if files:
-        expected_dir = Path("/") if expected_reason == "file system root" else tmp_path
+        expected_dir = (
+            Path(tmp_path.anchor) if expected_reason == "file system root" else tmp_path
+        )
+
         for file in files:
             (tmp_path / file).touch()
     else:

numpydoc/tests/hooks/test_validate_hook.py

@@ -1,6 +1,7 @@
 """Test the numpydoc validate pre-commit hook."""
 
 import inspect
+import re
 from pathlib import Path
 
 import pytest
@@ -25,42 +26,42 @@ def test_validate_hook(example_module, config, capsys):
     """Test that a file is correctly processed in the absence of config files."""
 
     expected = inspect.cleandoc(
-        """
-        numpydoc/tests/hooks/example_module.py:4: ES01 No extended summary found
+        f"""
+        {example_module!s}:4: ES01 No extended summary found
 
-        numpydoc/tests/hooks/example_module.py:4: PR01 Parameters {'name'} not documented
+        {example_module!s}:4: PR01 Parameters {{'name'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:4: SA01 See Also section not found
+        {example_module!s}:4: SA01 See Also section not found
 
-        numpydoc/tests/hooks/example_module.py:4: EX01 No examples section found
+        {example_module!s}:4: EX01 No examples section found
 
-        numpydoc/tests/hooks/example_module.py:8: ES01 No extended summary found
+        {example_module!s}:8: ES01 No extended summary found
 
-        numpydoc/tests/hooks/example_module.py:8: SA01 See Also section not found
+        {example_module!s}:8: SA01 See Also section not found
 
-        numpydoc/tests/hooks/example_module.py:8: EX01 No examples section found
+        {example_module!s}:8: EX01 No examples section found
 
-        numpydoc/tests/hooks/example_module.py:11: GL08 The object does not have a docstring
+        {example_module!s}:11: GL08 The object does not have a docstring
 
-        numpydoc/tests/hooks/example_module.py:17: ES01 No extended summary found
+        {example_module!s}:17: ES01 No extended summary found
 
-        numpydoc/tests/hooks/example_module.py:17: PR01 Parameters {'**kwargs'} not documented
+        {example_module!s}:17: PR01 Parameters {{'**kwargs'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR07 Parameter "*args" has no description
+        {example_module!s}:17: PR07 Parameter "*args" has no description
 
-        numpydoc/tests/hooks/example_module.py:17: SA01 See Also section not found
+        {example_module!s}:17: SA01 See Also section not found
 
-        numpydoc/tests/hooks/example_module.py:17: EX01 No examples section found
+        {example_module!s}:17: EX01 No examples section found
 
-        numpydoc/tests/hooks/example_module.py:26: SS05 Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
+        {example_module!s}:26: SS05 Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
 
-        numpydoc/tests/hooks/example_module.py:26: ES01 No extended summary found
+        {example_module!s}:26: ES01 No extended summary found
 
-        numpydoc/tests/hooks/example_module.py:26: SA01 See Also section not found
+        {example_module!s}:26: SA01 See Also section not found
 
-        numpydoc/tests/hooks/example_module.py:26: EX01 No examples section found
+        {example_module!s}:26: EX01 No examples section found
 
-        numpydoc/tests/hooks/example_module.py:30: GL08 The object does not have a docstring
+        {example_module!s}:30: GL08 The object does not have a docstring
         """
     )
 
@@ -76,18 +77,18 @@ def test_validate_hook_with_ignore(example_module, capsys):
     """
 
     expected = inspect.cleandoc(
-        """
-        numpydoc/tests/hooks/example_module.py:4: PR01 Parameters {'name'} not documented
+        f"""
+        {example_module!s}:4: PR01 Parameters {{'name'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:11: GL08 The object does not have a docstring
+        {example_module!s}:11: GL08 The object does not have a docstring
 
-        numpydoc/tests/hooks/example_module.py:17: PR01 Parameters {'**kwargs'} not documented
+        {example_module!s}:17: PR01 Parameters {{'**kwargs'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR07 Parameter "*args" has no description
+        {example_module!s}:17: PR07 Parameter "*args" has no description
 
-        numpydoc/tests/hooks/example_module.py:26: SS05 Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
+        {example_module!s}:26: SS05 Summary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")
 
-        numpydoc/tests/hooks/example_module.py:30: GL08 The object does not have a docstring
+        {example_module!s}:30: GL08 The object does not have a docstring
         """
     )
 
@@ -123,14 +124,14 @@ def test_validate_hook_with_toml_config(example_module, tmp_path, capsys):
         )
 
     expected = inspect.cleandoc(
-        """
-        numpydoc/tests/hooks/example_module.py:4: PR01 Parameters {'name'} not documented
+        f"""
+        {example_module!s}:4: PR01 Parameters {{'name'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR01 Parameters {'**kwargs'} not documented
+        {example_module!s}:17: PR01 Parameters {{'**kwargs'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR07 Parameter "*args" has no description
+        {example_module!s}:17: PR07 Parameter "*args" has no description
 
-        numpydoc/tests/hooks/example_module.py:30: GL08 The object does not have a docstring
+        {example_module!s}:30: GL08 The object does not have a docstring
         """
     )
 
@@ -158,14 +159,14 @@ def test_validate_hook_with_setup_cfg(example_module, tmp_path, capsys):
         )
 
     expected = inspect.cleandoc(
-        """
-        numpydoc/tests/hooks/example_module.py:4: PR01 Parameters {'name'} not documented
+        f"""
+        {example_module!s}:4: PR01 Parameters {{'name'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR01 Parameters {'**kwargs'} not documented
+        {example_module!s}:17: PR01 Parameters {{'**kwargs'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR07 Parameter "*args" has no description
+        {example_module!s}:17: PR07 Parameter "*args" has no description
 
-        numpydoc/tests/hooks/example_module.py:30: GL08 The object does not have a docstring
+        {example_module!s}:30: GL08 The object does not have a docstring
         """
     )
 
@@ -203,10 +204,10 @@ def test_validate_hook_exclude_option_pyproject(example_module, tmp_path, capsys
         )
 
     expected = inspect.cleandoc(
-        """
-        numpydoc/tests/hooks/example_module.py:4: PR01 Parameters {'name'} not documented
+        f"""
+        {example_module!s}:4: PR01 Parameters {{'name'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:30: GL08 The object does not have a docstring
+        {example_module!s}:30: GL08 The object does not have a docstring
         """
     )
 
@@ -234,12 +235,12 @@ def test_validate_hook_exclude_option_setup_cfg(example_module, tmp_path, capsys
         )
 
     expected = inspect.cleandoc(
-        """
-        numpydoc/tests/hooks/example_module.py:4: PR01 Parameters {'name'} not documented
+        f"""
+        {example_module!s}:4: PR01 Parameters {{'name'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR01 Parameters {'**kwargs'} not documented
+        {example_module!s}:17: PR01 Parameters {{'**kwargs'}} not documented
 
-        numpydoc/tests/hooks/example_module.py:17: PR07 Parameter "*args" has no description
+        {example_module!s}:17: PR07 Parameter "*args" has no description
         """
     )
 
@@ -249,16 +250,17 @@ def test_validate_hook_exclude_option_setup_cfg(example_module, tmp_path, capsys
 
 
 @pytest.mark.parametrize(
-    "regex, expected_code",
-    [(".*(/|\\\\)example.*\.py", 0), (".*/non_existent_match.*\.py", 1)],
+    "file_exists, expected_code",
+    [(True, 0), (False, 1)],
 )
 def test_validate_hook_exclude_files_option_pyproject(
-    example_module, regex, expected_code, tmp_path
+    example_module, file_exists, expected_code, tmp_path
 ):
     """
     Test that the hook correctly processes the toml config and either includes
     or excludes files based on the `exclude_files` option.
     """
+    exclude = str(example_module) if file_exists else "does_not_exist.py"
 
     with open(tmp_path / "pyproject.toml", "w") as config_file:
         config_file.write(
@@ -276,7 +278,7 @@ def test_validate_hook_exclude_files_option_pyproject(
                     '^Creates',
                 ]
                 exclude_files = [
-                    '{regex}',
+                    '{re.escape(exclude)}',
                 ]"""
             )
         )
@@ -286,16 +288,17 @@ def test_validate_hook_exclude_files_option_pyproject(
 
 
 @pytest.mark.parametrize(
-    "regex, expected_code",
-    [(".*(/|\\\\)example.*\.py", 0), (".*/non_existent_match.*\.py", 1)],
+    "file_exists, expected_code",
+    [(True, 0), (False, 1)],
 )
 def test_validate_hook_exclude_files_option_setup_cfg(
-    example_module, regex, expected_code, tmp_path
+    example_module, file_exists, expected_code, tmp_path
 ):
     """
     Test that the hook correctly processes the setup config and either includes
     or excludes files based on the `exclude_files` option.
     """
+    exclude = str(example_module) if file_exists else "does_not_exist.py"
 
     with open(tmp_path / "setup.cfg", "w") as config_file:
         config_file.write(
@@ -305,7 +308,7 @@ def test_validate_hook_exclude_files_option_setup_cfg(
                 checks = all,EX01,SA01,ES01
                 exclude = \\.NewClass$,\\.__init__$
                 override_SS05 = ^Creates
-                exclude_files = {regex}
+                exclude_files = {re.escape(exclude)}
                 """
             )
         )

numpydoc/tests/test_docscrape.py

@@ -5,7 +5,6 @@
 from copy import deepcopy
 
 import pytest
-from pytest import warns as assert_warns
 
 from numpydoc.docscrape import ClassDoc, FunctionDoc, NumpyDocString, get_doc_object
 
@@ -751,7 +750,7 @@ class Dummy:
 
 def test_see_also_trailing_comma_warning():
     warnings.filterwarnings("error")
-    with assert_warns(
+    with pytest.warns(
         Warning,
         match="Unexpected comma or period after function list at index 43 of line .*",
     ):

pyproject.toml

@@ -47,7 +47,6 @@ default = [
 ]
 dev = [
     'pre-commit>=3.3',
-    "tomli; python_version < '3.11'",
     { include-group = "doc" },
     { include-group = "test" }
 ]
@@ -171,6 +170,7 @@ attr = 'numpydoc.__version__'
 [tool.setuptools.package-data]
 numpydoc = [
     'tests/test_*.py',
+    'tests/hooks/test_*.py',
     'tests/tinybuild/Makefile',
     'tests/tinybuild/index.rst',
     'tests/tinybuild/*.py',