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

[ev-br]

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.

[ev-br]

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]

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]

triggered now - the joys of spammer-protection:)

[ev-br]

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]

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]

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

[rgommers]

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

[ev-br]

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]

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?

[agriyakhetarpal]

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

[ev-br]

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

[ev-br]

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]

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