Use `scipy-doctest` instead of `refguide-check` #747

ev-br · 2024-06-02T20:18:29Z

SciPy has recently refactored its refguide-check utility into a separate pip-installable package and added integration of the modified doctesting with pytest. This PR switches the refguide-check run (which uses the utility vendored from scipy) to this refactored way.

There are several minor tweaks to docstrings --- I'm actually not sure all the affected docstrings were checked previously (but they are now):

Explicit $ doctest: comments are no longer needed
A refactor of the ContinuousWavelet example is to avoid a DeprecationWarning from matplotlib 3.7
Some whitespace tweaks where the printing is non-standard enough for the tool to give up and fall back to the (whitespace-sensitive) vanilla doctest checker.

The pytest incantations to run doctesting are explicit on the CI --- in SciPy, these are hidden behind the dev.py smoke-docs interface.

$ pytest --doctest-modules --pyargs pywt -v --doctest-collect=api ... pywt/__init__.py::pywt.ContinuousWavelet.wavefun PASSED [ 3%] pywt/__init__.py::pywt.Modes PASSED [ 6%] pywt/__init__.py::pywt.Wavelet.wavefun PASSED [ 9%] pywt/__init__.py::pywt.array_to_coeffs PASSED [ 12%] pywt/__init__.py::pywt.coeffs_to_array PASSED [ 16%] pywt/__init__.py::pywt.cwt PASSED [ 19%] pywt/__init__.py::pywt.dwt PASSED [ 22%] pywt/__init__.py::pywt.dwt2 PASSED [ 25%] pywt/__init__.py::pywt.dwt_max_level PASSED [ 29%] pywt/__init__.py::pywt.dwtn_max_level PASSED [ 32%] pywt/__init__.py::pywt.families PASSED [ 35%] pywt/__init__.py::pywt.fswavedecn PASSED [ 38%] pywt/__init__.py::pywt.idwt PASSED [ 41%] pywt/__init__.py::pywt.idwt2 PASSED [ 45%] pywt/__init__.py::pywt.integrate_wavelet PASSED [ 48%] pywt/__init__.py::pywt.iswt PASSED [ 51%] pywt/__init__.py::pywt.iswt2 PASSED [ 54%] pywt/__init__.py::pywt.iswtn PASSED [ 58%] pywt/__init__.py::pywt.ravel_coeffs PASSED [ 61%] pywt/__init__.py::pywt.threshold PASSED [ 64%] pywt/__init__.py::pywt.unravel_coeffs PASSED [ 67%] pywt/__init__.py::pywt.upcoef PASSED [ 70%] pywt/__init__.py::pywt.wavedec PASSED [ 74%] pywt/__init__.py::pywt.wavedec2 PASSED [ 77%] pywt/__init__.py::pywt.wavedecn PASSED [ 80%] pywt/__init__.py::pywt.wavedecn_shapes PASSED [ 83%] pywt/__init__.py::pywt.wavedecn_size PASSED [ 87%] pywt/__init__.py::pywt.wavelist PASSED [ 90%] pywt/__init__.py::pywt.waverec PASSED [ 93%] pywt/__init__.py::pywt.waverec2 PASSED [ 96%] pywt/__init__.py::pywt.waverecn PASSED [100%] ================================== 31 passed in 0.80s =====================

Makes this green: $ pytest --doctest-glob=*rst doc/source/regression/ -vs

agriyakhetarpal

Thanks for doing this, @ev-br! All of the changes look good to me. I would suggest leaving out the files under doc/source/regression/, though – they are being converted to Markdown-style notebooks in gh-741, which means that the changes to them won't be needed since MyST-NB will execute them. That PR is close to getting merged and should be done by today or so.

The script can do two things: - run modified doctests; this is done via smoke-docs / scipy-doctests now - check __all__ lists vs refguide entries; this was already disabled, on CI at least

ev-br · 2024-06-03T15:50:33Z

Thanks @agriyakhetarpal . Rolled back all changes to *rst files, removed the corresponding stanza from the CI run, and removed the refguide-check utility as "not used anymore". Would be nice if you could trigger the CI run for me, would you?

agriyakhetarpal · 2024-06-03T15:53:13Z

Thanks! I tried but it turns out I don't have enough permissions to trigger a CI run – tagging @rgommers who can do this for you.

rgommers · 2024-06-03T16:21:33Z

triggered now - the joys of spammer-protection:)

ev-br · 2024-06-03T17:53:04Z

Thanks Ralf! So the CI is green, thus the question is whether y'all want it :-). And if you do, whether you want a spin command to to mimic scipy's python dev.py smoke-docs.

rgommers · 2024-06-03T18:09:10Z

Yes, and yes. thanks:)

And if you do, whether you want a spin command to to mimic scipy's python dev.py smoke-docs.

Do you want to include that here, or separately?

ev-br · 2024-06-03T18:15:17Z

A follow-up PR would not require restarting the CI for me, so seems easier :-).

rgommers · 2024-06-03T18:25:49Z

Did you actually notice the doctesting happening in CI? I only see REFGUIDE_CHECK: [0] in test.yml.

ev-br · 2024-06-03T18:32:33Z

Indeed! So it was never actually running on CI, huh :-). Pushed a commit to switch it always on. Depending on how you want to play this, can iterate the CI in follow-ups or here. (If the latter, a new commit asks for one more confirmation I'm not a crypto miner)

rgommers · 2024-06-03T19:12:00Z

ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'util/readthedocs/requirements.txt'

If it becomes a pain for CI not to run, maybe submit a trivial typo/change PR that can be merged straight away?

.github/workflows/tests.yml

Co-authored-by: Agriya Khetarpal <[email protected]>

agriyakhetarpal · 2024-06-04T16:20:19Z

With the latest failure, maybe we should do cd .. rather, much easier than fixing the paths in-place every time.

.github/workflows/tests.yml

Co-authored-by: Agriya Khetarpal <[email protected]>

ev-br · 2024-06-04T16:28:26Z

Since sphinx on CI, which is the source of the failures, is not really related, maybe it's best to separate the fixes.

.github/workflows/tests.yml

ev-br · 2024-06-06T18:55:13Z

Okay, current status:

smoke-docs runs fine on CI
sphinx-build was disabled on CI, is still disabled on CI.
attempting to run sphinx-build locally shows a bunch of errors, so there's some structural problem with it.
However, docs build on readthedocs. Meaning, the problem is with the sphinx-build invocation which did not run on CI previously.

So how about not fixing the sphinx-build check in this PR? If that's OK, the PR is ready from my side.

agriyakhetarpal · 2024-06-07T04:01:19Z

I'll hope to fix the sphinx-build checks in a separate PR after this – I would be fine with this getting merged.

rgommers

Thanks @ev-br, this looks quite nice! Overall much cleaner docs, in addition to getting rid of the refguide_check.py script which is great. Just a few small comments.

pywt/data/_readers.py

pywt/_extensions/_pywt.pyx

rgommers · 2024-06-18T12:04:38Z

.github/workflows/tests.yml

-              pip install -r util/readthedocs/requirements.txt
-              sphinx-build -b html -W --keep-going -d _build/doctrees . doc/source doc/build
+              cd ..
+            # XXX sphinx build is broken on CI


What is happening here? Debug left-over, or is something actually broken right now? If so, I think three lines can be safely deleted. The separate CI job to build the docs with the ReadTheDocs integration is green.

The RTD job is not building the docs with -W, I guess: python -m sphinx -T -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html. Not that there are any warnings because we're already warning-free.

Indeed, this sphinx-build incantation did not previously run on CI because REFGUIDE-CHECK: [0], and was always broken. There's a standing offer to fix this in a follow-up though :-). #747 (comment)

Okay thanks, let's do that - offer is appreciated:)

rgommers

LGTM now and CI is happy, so in it goes. Thanks @ev-br! And thanks @agriyakhetarpal for the review and help.

ev-br added 3 commits June 2, 2024 18:58

DOC: normalize whitespace in *.rst

fc0339a

Makes this green: $ pytest --doctest-glob=*rst doc/source/regression/ -vs

CI: run smoke-docs on CI

b616b0c

ev-br changed the title ~~Use~~ Use scipy-doctest instead of refguide-check Jun 2, 2024

MAINT: no need to touch conftest

dce8b99

agriyakhetarpal reviewed Jun 3, 2024

View reviewed changes

agriyakhetarpal added maintenance documentation labels Jun 3, 2024

agriyakhetarpal added this to the v1.7.0 milestone Jun 3, 2024

ev-br added 2 commits June 3, 2024 18:15

TST: do not doctest tutorials

0945b56

TST: remove redguide-check.py

5efbdda

The script can do two things: - run modified doctests; this is done via smoke-docs / scipy-doctests now - check __all__ lists vs refguide entries; this was already disabled, on CI at least

CI: turn smoke-docs on on CI

08f41a1

agriyakhetarpal reviewed Jun 4, 2024

View reviewed changes

.github/workflows/tests.yml Outdated Show resolved Hide resolved

Update .github/workflows/tests.yml

3be8628

Co-authored-by: Agriya Khetarpal <[email protected]>

agriyakhetarpal reviewed Jun 4, 2024

View reviewed changes

.github/workflows/tests.yml Outdated Show resolved Hide resolved

Update .github/workflows/tests.yml

e130385

Co-authored-by: Agriya Khetarpal <[email protected]>

ev-br commented Jun 4, 2024

View reviewed changes

.github/workflows/tests.yml Outdated Show resolved Hide resolved

.github/workflows/tests.yml Outdated Show resolved Hide resolved

Comment out the sphinx build

e412d87

rgommers reviewed Jun 18, 2024

View reviewed changes

ev-br added 3 commits June 22, 2024 13:47

DOC: fix typo in data/_readers/ascent docstring

e802a9a

DOC: address a review comment

6b29578

MAINT: smoke-docs pywt.data, too

f9258d3

rgommers approved these changes Jun 25, 2024

View reviewed changes

rgommers merged commit f2b3d58 into PyWavelets:main Jun 25, 2024
16 checks passed

agriyakhetarpal mentioned this pull request Jun 25, 2024

DOC: Fix failing documentation build #754

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use `scipy-doctest` instead of `refguide-check` #747

Use `scipy-doctest` instead of `refguide-check` #747

ev-br commented Jun 2, 2024 •

edited

Loading

agriyakhetarpal left a comment

ev-br commented Jun 3, 2024

agriyakhetarpal commented Jun 3, 2024

rgommers commented Jun 3, 2024

ev-br commented Jun 3, 2024

rgommers commented Jun 3, 2024

ev-br commented Jun 3, 2024

rgommers commented Jun 3, 2024

ev-br commented Jun 3, 2024

rgommers commented Jun 3, 2024

agriyakhetarpal commented Jun 4, 2024

ev-br commented Jun 4, 2024 •

edited

Loading

ev-br commented Jun 6, 2024

agriyakhetarpal commented Jun 7, 2024

rgommers left a comment

rgommers Jun 18, 2024

agriyakhetarpal Jun 18, 2024

ev-br Jun 22, 2024

rgommers Jun 25, 2024

rgommers left a comment

Use scipy-doctest instead of refguide-check #747

Use scipy-doctest instead of refguide-check #747

Conversation

ev-br commented Jun 2, 2024 • edited Loading

agriyakhetarpal left a comment

Choose a reason for hiding this comment

ev-br commented Jun 3, 2024

agriyakhetarpal commented Jun 3, 2024

rgommers commented Jun 3, 2024

ev-br commented Jun 3, 2024

rgommers commented Jun 3, 2024

ev-br commented Jun 3, 2024

rgommers commented Jun 3, 2024

ev-br commented Jun 3, 2024

rgommers commented Jun 3, 2024

agriyakhetarpal commented Jun 4, 2024

ev-br commented Jun 4, 2024 • edited Loading

ev-br commented Jun 6, 2024

agriyakhetarpal commented Jun 7, 2024

rgommers left a comment

Choose a reason for hiding this comment

rgommers Jun 18, 2024

Choose a reason for hiding this comment

agriyakhetarpal Jun 18, 2024

Choose a reason for hiding this comment

ev-br Jun 22, 2024

Choose a reason for hiding this comment

rgommers Jun 25, 2024

Choose a reason for hiding this comment

rgommers left a comment

Choose a reason for hiding this comment

Use `scipy-doctest` instead of `refguide-check` #747

Use `scipy-doctest` instead of `refguide-check` #747

ev-br commented Jun 2, 2024 •

edited

Loading

ev-br commented Jun 4, 2024 •

edited

Loading