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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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]

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.

[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.

[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.

[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.

[rgommers]

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.

[agriyakhetarpal]

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.

[ev-br]

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)

[rgommers]

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.