DOC, BUG: Fix error in heading remapping for custom scipy.optimize:function domain directive
#15443
Conversation
brandondavid
added
Documentation
Fixes a bug that replaces the Returns heading with an incorrect heading size in the generated docstring. This will cause warnings (treated as errors) with numpydoc 1.2.
rossbar
force-pushed
the
doc/updates-for-numpydoc-1.2rc1
branch
from
6ebf6e3
to
a5f39ab
Compare
|
Okay, now that #15789 is in I've rebased and removed the numpydoc upper bound pins as discussed in the other PR. Now the passing doc builds in CI are indicative that the fix in a2a9a67 gets things working with the latest numpydoc (1.2). AFAICT the CI failures are unrelated. A quick summary of this PR:
|
There was a problem hiding this comment.
Agreed that the CI failures are not related. The changes here all look sensible and the unpinning here already had a "thumbs up" from a few core devs in the related PR.
I'm happy to trust your expertise on the changes in doc/source/scipyoptdoc.py, which is the only thing that looks a bit tricky here. I did a spot check on some of the optimize docs in the CI-generated docs artifact and they seem "ok," though the fact that the docs build successfully with latest numpydoc is likely a better indicator than my visual inspection anyway.
|
Thanks Ross |
| @@ -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" | |||
There was a problem hiding this comment.
Ark it would have been good to test if we could then remove the pin on Jinja2. This is why I pinged you on the other issue.
There was a problem hiding this comment.
My bad, I missed this somehow "/. FWIW I tried this locally without the Jinja pin and everything worked.
This is just a cleanup for numpydoc that was left after already being unpinned in scipy#15443 This is unrelated to the current PR.
rgommers
added
the
backport-candidate
|
This was either already in the release branch or recently merged in, so stripping the backport label. |
tylerjereddy
removed
the
backport-candidate
There is a bug in
.. scipy.optimize::functionthat causes the heading under theReturnssection of the docstrings to be replaced with a heading with the wrong length. The numpydoc 1.2rc1 release candidate will raise a UserWarning when there is an incorrect header length. Because of the way the doc build is configured, thisUserWarningis elevated to an exception that terminates the scipy doc build process, so this fix is necessary to build the scipy docs with numpydoc 1.2.I also had to add an extra warnings filter for a distutils deprecation warning to get the docs to build locally. Not sure if this is the desired fix, but I thought I'd include it here just in case. I'm happy to drop 6ebf6e3 if there is a different preferred solution, or if it's preferred to be handled in a different PR.