Stop using jupyter-sphinx extension in docs builds by mtreinish · Pull Request #9346 · Qiskit/qiskit

mtreinish · 2023-01-05T20:47:47Z

Summary

The use of the jupyter-sphinx plugin has been increasingly unreliable over time. While convinient to use jupyter to print the code and rendered output in practice this extension is exceedingly fragile. The nature of how the plugin launches jupyter kernels and executes code causes it to be prone to failure and weird issues. A race condition in this machinery is causing a high non-deterministic failure rate in CI right now preventing us from reliably building documentation. This commit removes the use of the jupyter-sphinx extension from the documentation. For the most part a drop-in replacement is the plot directive from matplotlib that enables executing code and visualizing the result as part of the documentation build. But it does this more simply through exec() which will be much more reliable. In many of the cases jupyter-execute wasn't even needed because no output was shown in those cases a simple code-block is used instead.

For release notes, new release notes are updated to use plot where necessary but for historical release notes all jupyter-execute directives are converted to code-blocks. This was done for sanity to avoid having to manually update hundreds of release notes over the past 3 years.

This also enables us to enable parallel builds as jupyter-sphinx was the extension which was unreliable in a parallel context. Doing this can greatly speed up documentation builds (although the impact in CI will be limited as we only have 2 vCPUs in the CI workers).

Details and comments

The use of the jupyter-sphinx plugin has been increasingly unreliable over time. While convinient to use jupyter to print the code and rendered output in practice this extension is exceedingly fragile. The nature of how the plugin launches jupyter kernels and executes code causes it to be prone to failure and weird issues. A race condition in this machinery is causing a high non-deterministic failure rate in CI right now preventing us from reliably building documentation. This commit removes the use of the jupyter-sphinx extension from the documentation. For the most part a drop-in replacement is the ``plot`` directive from matplotlib that enables executing code and visualizing the result as part of the documentation build. But it does this more simply through ``exec()`` which will be much more reliable. In many of the cases jupyter-execute wasn't even needed because no output was shown in those cases a simple code-block is used instead. For release notes, new release notes are updated to use plot where necessary but for historical release notes all jupyter-execute directives are converted to code-blocks. This was done for sanity to avoid having to manually update hundreds of release notes over the past 3 years. This also enables us to enable parallel builds as jupyter-sphinx was the extension which was unreliable in a parallel context. Doing this can greatly speed up documentation builds (although the impact in CI will be limited as we only have 2 vCPUs in the CI workers).

qiskit-bot · 2023-01-05T20:47:56Z

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the the following people are requested to review this:

coveralls · 2023-01-05T21:57:24Z

Pull Request Test Coverage Report for Build 3855962119

2 of 17 (11.76%) changed or added relevant lines in 2 files are covered.
2 unchanged lines in 2 files lost coverage.
Overall coverage decreased (-0.05%) to 84.537%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/visualization/gate_map.py	2	3	66.67%
qiskit/tools/jupyter/library.py	0	14	0.0%

Files with Coverage Reduction	New Missed Lines	%
qiskit/tools/jupyter/library.py	1	0%
qiskit/visualization/counts_visualization.py	1	79.87%

Totals
Change from base Build 3855353443:	-0.05%
Covered Lines:	64006
Relevant Lines:	75714

💛 - Coveralls

jakelishman

Very minor comments aside, I guess we need to get this in. I'm glad to see the back of jupyter-sphinx in the end. It really has caused a lot of problems, though it isn't ideal that we're losing a lot of the soft doctesting that we had before.

jakelishman · 2023-01-06T11:39:44Z


-    # TODO: This example should use a real mock backend.
-    backend = FakeOpenPulse3Q()
+   # TODO: This example should use a real mock backend.


jakelishman · 2023-01-06T11:49:41Z


-    .. jupyter-execute::
+    .. code-block::

        import math



This code block continues on to use pulse which isn't defined in the block - it was notionally defined in a separate Jupyter kernel a couple of code-blocks above. I think that's probably fine, since the display is the same as it was before, and there's no output for users to copy/paste to see anyway, I'm just mentioning it.

Yeah, I did this on purpose because this section of the docs read more like a notebook to me and since we're not actually executing anything I left it as is so the rendering was the same.

jakelishman

Thanks! At some point we'll want to propagate the changes in the requirements up to the metapackage, but at the moment IBMQ still uses jupyter-execute a lot. I think that if we're lucky, we should still be able to build with that in place, and we can remove it once IBMQ is completely removed from the metapackage.

With the recent merge of Qiskit#9346 that stopped using the problematic jupyter-sphinx plugin we're no long blocked from running sphinx-build in parallel anymore. We had originally enabled this in Qiskit#4477 to get a speed boost during docs builds. However, we were forced to revert that in Qiskit#6539 because jupyter-sphinx was unreliable and had a race condition when 2 jupyter-execute blocks were run at the same time (see Qiskit#5904 for more details). Since we've removed the jupyter-sphinx usage that is no longer a problem and we can reliably run parallel sphinx builds again. This commit makes that change and changes the default sphinx-build behavior when run via tox (as is done via ci) to use all available system cores to perform a sphinx build. Annecdoteally this provides a nice speed up, on my local workstation a full docs build went from taking 8min 42 seconds for a serial build to 2min 35sec with a parallel build.

With the recent merge of #9346 that stopped using the problematic jupyter-sphinx plugin we're no long blocked from running sphinx-build in parallel anymore. We had originally enabled this in #4477 to get a speed boost during docs builds. However, we were forced to revert that in #6539 because jupyter-sphinx was unreliable and had a race condition when 2 jupyter-execute blocks were run at the same time (see #5904 for more details). Since we've removed the jupyter-sphinx usage that is no longer a problem and we can reliably run parallel sphinx builds again. This commit makes that change and changes the default sphinx-build behavior when run via tox (as is done via ci) to use all available system cores to perform a sphinx build. Annecdoteally this provides a nice speed up, on my local workstation a full docs build went from taking 8min 42 seconds for a serial build to 2min 35sec with a parallel build. Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Stop using jupyter-sphinx extension in docs builds The use of the jupyter-sphinx plugin has been increasingly unreliable over time. While convinient to use jupyter to print the code and rendered output in practice this extension is exceedingly fragile. The nature of how the plugin launches jupyter kernels and executes code causes it to be prone to failure and weird issues. A race condition in this machinery is causing a high non-deterministic failure rate in CI right now preventing us from reliably building documentation. This commit removes the use of the jupyter-sphinx extension from the documentation. For the most part a drop-in replacement is the ``plot`` directive from matplotlib that enables executing code and visualizing the result as part of the documentation build. But it does this more simply through ``exec()`` which will be much more reliable. In many of the cases jupyter-execute wasn't even needed because no output was shown in those cases a simple code-block is used instead. For release notes, new release notes are updated to use plot where necessary but for historical release notes all jupyter-execute directives are converted to code-blocks. This was done for sanity to avoid having to manually update hundreds of release notes over the past 3 years. This also enables us to enable parallel builds as jupyter-sphinx was the extension which was unreliable in a parallel context. Doing this can greatly speed up documentation builds (although the impact in CI will be limited as we only have 2 vCPUs in the CI workers). * Fix tests and lint * Revert accidental change to tox.ini * Fix capitalization of GHZ circuit * Cleanup circuit library visualization function

With the recent merge of Qiskit#9346 that stopped using the problematic jupyter-sphinx plugin we're no long blocked from running sphinx-build in parallel anymore. We had originally enabled this in Qiskit#4477 to get a speed boost during docs builds. However, we were forced to revert that in Qiskit#6539 because jupyter-sphinx was unreliable and had a race condition when 2 jupyter-execute blocks were run at the same time (see Qiskit#5904 for more details). Since we've removed the jupyter-sphinx usage that is no longer a problem and we can reliably run parallel sphinx builds again. This commit makes that change and changes the default sphinx-build behavior when run via tox (as is done via ci) to use all available system cores to perform a sphinx build. Annecdoteally this provides a nice speed up, on my local workstation a full docs build went from taking 8min 42 seconds for a serial build to 2min 35sec with a parallel build. Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Stop using jupyter-sphinx extension in docs builds The use of the jupyter-sphinx plugin has been increasingly unreliable over time. While convinient to use jupyter to print the code and rendered output in practice this extension is exceedingly fragile. The nature of how the plugin launches jupyter kernels and executes code causes it to be prone to failure and weird issues. A race condition in this machinery is causing a high non-deterministic failure rate in CI right now preventing us from reliably building documentation. This commit removes the use of the jupyter-sphinx extension from the documentation. For the most part a drop-in replacement is the ``plot`` directive from matplotlib that enables executing code and visualizing the result as part of the documentation build. But it does this more simply through ``exec()`` which will be much more reliable. In many of the cases jupyter-execute wasn't even needed because no output was shown in those cases a simple code-block is used instead. For release notes, new release notes are updated to use plot where necessary but for historical release notes all jupyter-execute directives are converted to code-blocks. This was done for sanity to avoid having to manually update hundreds of release notes over the past 3 years. This also enables us to enable parallel builds as jupyter-sphinx was the extension which was unreliable in a parallel context. Doing this can greatly speed up documentation builds (although the impact in CI will be limited as we only have 2 vCPUs in the CI workers). * Fix tests and lint * Revert accidental change to tox.ini * Fix capitalization of GHZ circuit * Cleanup circuit library visualization function

With the recent merge of Qiskit#9346 that stopped using the problematic jupyter-sphinx plugin we're no long blocked from running sphinx-build in parallel anymore. We had originally enabled this in Qiskit#4477 to get a speed boost during docs builds. However, we were forced to revert that in Qiskit#6539 because jupyter-sphinx was unreliable and had a race condition when 2 jupyter-execute blocks were run at the same time (see Qiskit#5904 for more details). Since we've removed the jupyter-sphinx usage that is no longer a problem and we can reliably run parallel sphinx builds again. This commit makes that change and changes the default sphinx-build behavior when run via tox (as is done via ci) to use all available system cores to perform a sphinx build. Annecdoteally this provides a nice speed up, on my local workstation a full docs build went from taking 8min 42 seconds for a serial build to 2min 35sec with a parallel build. Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

The Jupyter Sphinx integration is currently unable to properly suppress warnings resulting in prints to stderr [1]. This causes the docs to fail building properly. Qiskit Terra already removed the usage of `jupyter-execute` statements a while ago [2], so we are following suit in this regard, too. [1]: jupyter/jupyter-sphinx#178 [2]: Qiskit/qiskit#9346

* Implement the Tensor class * Always wrap scalar numbers into numpy array This matches what we did in the PolynomialTensor and avoids unnecessary complicated code to deal with Number objects where otherwise one always encounters an array. * Add qiskit_nature.settings.tensor_wrapping * Add release note * fix: remove jupyter-execute blocks The Jupyter Sphinx integration is currently unable to properly suppress warnings resulting in prints to stderr [1]. This causes the docs to fail building properly. Qiskit Terra already removed the usage of `jupyter-execute` statements a while ago [2], so we are following suit in this regard, too. [1]: jupyter/jupyter-sphinx#178 [2]: Qiskit/qiskit#9346 * fix: rework settings.tensor_wrapping as settings.tensor_unwrapping * docs: update documentaiton of PolynomialTensor now that Tensor exists --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

This has not been used since the switch away from using `jupyter-execute` in Qiskitgh-9346, so is neither maintained nor necessary. Any improvements to styling should be made to the new paths, not to these. These objects were originally intended only for the documentation so we expect user impact to be minimal, and the objects are not maintained anyway.

* Deprecate circuit-library Jupyter magic This has not been used since the switch away from using `jupyter-execute` in gh-9346, so is neither maintained nor necessary. Any improvements to styling should be made to the new paths, not to these. These objects were originally intended only for the documentation so we expect user impact to be minimal, and the objects are not maintained anyway. * Correct versions for deprecation * Add missing import

* Deprecate circuit-library Jupyter magic This has not been used since the switch away from using `jupyter-execute` in Qiskitgh-9346, so is neither maintained nor necessary. Any improvements to styling should be made to the new paths, not to these. These objects were originally intended only for the documentation so we expect user impact to be minimal, and the objects are not maintained anyway. * Correct versions for deprecation * Add missing import

* Implement the Tensor class * Always wrap scalar numbers into numpy array This matches what we did in the PolynomialTensor and avoids unnecessary complicated code to deal with Number objects where otherwise one always encounters an array. * Add qiskit_nature.settings.tensor_wrapping * Add release note * fix: remove jupyter-execute blocks The Jupyter Sphinx integration is currently unable to properly suppress warnings resulting in prints to stderr [1]. This causes the docs to fail building properly. Qiskit Terra already removed the usage of `jupyter-execute` statements a while ago [2], so we are following suit in this regard, too. [1]: jupyter/jupyter-sphinx#178 [2]: Qiskit/qiskit#9346 * fix: rework settings.tensor_wrapping as settings.tensor_unwrapping * docs: update documentaiton of PolynomialTensor now that Tensor exists --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Stop using jupyter-sphinx extension in docs builds The use of the jupyter-sphinx plugin has been increasingly unreliable over time. While convinient to use jupyter to print the code and rendered output in practice this extension is exceedingly fragile. The nature of how the plugin launches jupyter kernels and executes code causes it to be prone to failure and weird issues. A race condition in this machinery is causing a high non-deterministic failure rate in CI right now preventing us from reliably building documentation. This commit removes the use of the jupyter-sphinx extension from the documentation. For the most part a drop-in replacement is the ``plot`` directive from matplotlib that enables executing code and visualizing the result as part of the documentation build. But it does this more simply through ``exec()`` which will be much more reliable. In many of the cases jupyter-execute wasn't even needed because no output was shown in those cases a simple code-block is used instead. For release notes, new release notes are updated to use plot where necessary but for historical release notes all jupyter-execute directives are converted to code-blocks. This was done for sanity to avoid having to manually update hundreds of release notes over the past 3 years. This also enables us to enable parallel builds as jupyter-sphinx was the extension which was unreliable in a parallel context. Doing this can greatly speed up documentation builds (although the impact in CI will be limited as we only have 2 vCPUs in the CI workers). * Fix tests and lint * Revert accidental change to tox.ini * Fix capitalization of GHZ circuit * Cleanup circuit library visualization function

mtreinish requested review from a team, ShellyGarion, alexanderivrii, eggerdj, ikkoham, jyu00, manoelmarques, nonhermitian, woodsp-ibm and wshanks as code owners January 5, 2023 20:47

mtreinish added documentation Something is not clear or an error documentation Changelog: None Do not include in the GitHub Release changelog. labels Jan 5, 2023

mtreinish added 2 commits January 5, 2023 16:26

Fix tests and lint

ab94b44

Revert accidental change to tox.ini

e492e1e

mtreinish mentioned this pull request Jan 5, 2023

Pin nbconvert version for CI #9341

Closed

jakelishman reviewed Jan 6, 2023

View reviewed changes

This was referenced Jan 6, 2023

DNM: run docs build with extra debug verbosity #9344

Closed

Homepage in pip package page Qiskit/qiskit-metapackage#1641

Merged

mtreinish added 3 commits January 6, 2023 08:06

Fix capitalization of GHZ circuit

2ace0a4

Cleanup circuit library visualization function

fdbba3d

Merge remote-tracking branch 'origin/main' into no-more-jupyter-sphinx

39d007e

jakelishman approved these changes Jan 6, 2023

View reviewed changes

jakelishman added the automerge label Jan 6, 2023

mergify Bot merged commit 95a97ec into Qiskit:main Jan 6, 2023

mtreinish deleted the no-more-jupyter-sphinx branch January 6, 2023 16:32

mtreinish mentioned this pull request Jan 6, 2023

Re-enable parallel sphinx builds by default #9348

Merged

This was referenced Jan 9, 2023

Run doctests to validate code examples in documentation and limit jupyter-execute to visualization examples #7661

Open

Deprecate usage of jupyter-execute directive for code examples Qiskit/qiskit_sphinx_theme#164

Closed

HuangJunye mentioned this pull request Aug 11, 2023

Matplotlib plot directive doesn't show links to download generated figures and source code #10614

Open

jakelishman mentioned this pull request Apr 11, 2023

Deprecate circuit-library Jupyter magic #9940

Merged

Eric-Arellano mentioned this pull request May 16, 2023

Remove jupyter-execute from docs Qiskit/qiskit-metapackage#1735

Merged

HuangJunye mentioned this pull request May 23, 2023

Add examples for the NLocal class docstrings (#9080) #9302

Open

kt474 mentioned this pull request Apr 16, 2024

Deprecate qiskit-ibm-provider Qiskit/qiskit-ibm-provider#832

Merged

arnaucasau mentioned this pull request Nov 27, 2024

Replace jupyter-execute with plot from docs Qiskit/qiskit-ibm-runtime#2059

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stop using jupyter-sphinx extension in docs builds#9346

Stop using jupyter-sphinx extension in docs builds#9346
mergify[bot] merged 6 commits intoQiskit:mainfrom
mtreinish:no-more-jupyter-sphinx

mtreinish commented Jan 5, 2023

Uh oh!

qiskit-bot commented Jan 5, 2023

Uh oh!

coveralls commented Jan 5, 2023 •

edited

Loading

Uh oh!

jakelishman left a comment

Uh oh!

Uh oh!

jakelishman Jan 6, 2023

Uh oh!

jakelishman Jan 6, 2023

Uh oh!

mtreinish Jan 6, 2023

Uh oh!

Uh oh!

Uh oh!

jakelishman left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

mtreinish commented Jan 5, 2023

Summary

Details and comments

Uh oh!

qiskit-bot commented Jan 5, 2023

Uh oh!

coveralls commented Jan 5, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 3855962119

💛 - Coveralls

Uh oh!

jakelishman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jakelishman Jan 6, 2023

Choose a reason for hiding this comment

Uh oh!

jakelishman Jan 6, 2023

Choose a reason for hiding this comment

Uh oh!

mtreinish Jan 6, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jakelishman left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

coveralls commented Jan 5, 2023 •

edited

Loading