Merge pull request #15443 from rossbar/doc/updates-for-numpydoc-1.2rc1

DOC, BUG: Fix error in heading remapping for custom `scipy.optimize:function` domain directive
scipy · Mar 25, 2022 · fd252cb · fd252cb
2 parents fdc31f3 + a5f39ab
commit fd252cb
Show file tree

Hide file tree

Showing 5 changed files with 8 additions and 5 deletions.
diff --git a/ci/azure-travis-template.yaml b/ci/azure-travis-template.yaml
@@ -82,7 +82,7 @@ steps:
   - script: pip install pytest-cov coverage codecov
     displayName: 'Install coverage dependencies'
 - ${{ if eq(parameters.refguide_check, true) }}:
-  - script: pip install matplotlib sphinx==3.1 numpydoc==1.1 "Jinja2<=3.0.3"
+  - script: pip install matplotlib sphinx==3.1 numpydoc "Jinja2<=3.0.3"
     displayName: 'Install documentation dependencies'
   - script: sudo apt-get install -y wamerican-small
     displayName: 'Install word list (for csgraph tutorial)'

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -155,6 +155,7 @@
         r"OpenSSL\.rand is deprecated",  # OpenSSL package in linkcheck
         r"Using or importing the ABCs from",  # 3.5 importlib._bootstrap
         r"'contextfunction' is renamed to 'pass_context'",  # Jinja
+        r"distutils Version",  # distutils
         ):
     warnings.filterwarnings(  # deal with other modules having bad imports
         'ignore', message=".*" + key, category=DeprecationWarning)

diff --git a/doc/source/scipyoptdoc.py b/doc/source/scipyoptdoc.py
@@ -135,10 +135,12 @@ def remove_arg(arg):
             # Change "Options" to "Other Parameters", run numpydoc, reset
             new_lines = []
             for line in lines:
+                # Remap Options to the "Other Parameters" numpydoc section
+                # along with correct heading length
                 if line.strip() == 'Options':
                     line = "Other Parameters"
-                elif line.strip() == "-"*len('Options'):
-                    line = "-"*len("Other Parameters")
+                    new_lines.extend([line, "-"*len(line)])
+                    continue
                 new_lines.append(line)
             # use impl_name instead of name here to avoid duplicate refs
             mangle_docstrings(env.app, 'function', impl_name,

diff --git a/doc_requirements.txt b/doc_requirements.txt
@@ -3,5 +3,5 @@
 Sphinx!=3.1.0, !=4.1.0
 pydata-sphinx-theme>=0.6.1
 sphinx-panels>=0.5.2
-numpydoc==1.1
+numpydoc
 matplotlib>2
diff --git a/pyproject.toml b/pyproject.toml
@@ -100,7 +100,7 @@ doc = [
     "pydata-sphinx-theme>=0.6.1",
     "sphinx-panels>=0.5.2",
     "matplotlib>2",
-    "numpydoc==1.1.0",
+    "numpydoc",
 ]
 dev = [
     "mypy",