Add sphinx gallery to docs #2323

ixjlyons · 2022-06-05T00:04:25Z

https://pyqtgraph--2323.org.readthedocs.build/en/2323/examples/index.html

I'm thinking once this is working relatively well, we can start tackling some other improvements like categorizing examples in a separate PR.

Fix merge conflicts
Track down the examples that are giving "RuntimeError: Internal C++ object (ViewBox) already deleted". Ideally we can fix them, but for now either PyQt5 or PyQt6 will treat them like warnings and still output a rendering that looks reasonable. PyQt6 appears to not be installable on readthedocs for now...
Take another look at how VisPy's scraper works - is it feasible for us to capture/render animations? e.g. https://vispy.org/gallery/gloo/animate_images.html#sphx-glr-gallery-gloo-animate-images-py
Work around the __file__ issue in some of the examples (https://sphinx-gallery.github.io/stable/faq.html#why-is-file-not-defined-what-can-i-use)
Can we get intersphinx working with Qt/bindings somehow so things like QMainWindow used in an example links to the Qt API page for it? That would be neeeeat, but I suspect unlikely with our abstraction package (edit: haven't gotten it to work with https://doc.qt.io/qtforpython/ thought it might be feasible?)
Get GL examples working

- Add title to each example docstring - Add examples README - Sphinx conf is a total hack right now, need to figure out something better, potentially rename examples

Still seeing some "C++ object deleted..." errors, but at least with PyQt6, these seem to not be fatal.

PyQt6 failed to install on readthedocs

pyqtgraph/__init__.py

ixjlyons · 2022-06-05T00:40:05Z

pyqtgraph/examples/_RunExampleApp.py

@@ -4,7 +4,7 @@
 not run twice.
 """

-from ExampleApp import ExampleLoader
+from _ExampleApp import ExampleLoader


I guess I should check - this doesn't break one of the various ways of running the example application does it? This and some of the other file renames weren't strictly necessary but it made coming up with an ignore_pattern a little easier.

ixjlyons · 2022-06-05T00:42:49Z

pyqtgraph/examples/CLIexample.py

@@ -1,20 +1,25 @@
 """
-Display a plot and an image with minimal setup. 
+CLI Example


"Tutorialized" this example https://pyqtgraph--2323.org.readthedocs.build/en/2323/examples/CLIexample.html#sphx-glr-examples-cliexample-py

Was wondering if this example even worked anymore now that interactive mode doesn't necessarily work with some bindings.

That's a good point, looks like this usage currently only works with PyQt{5,6}. So maybe not the best example to iterate on, but I believe this would still work with PySide at least for the docs build. I use PySide2 for qtgallery and the iterative example works.

ixjlyons · 2022-06-05T18:48:38Z

Playing with the CLI example, I found that with PyQt5, running that example interactively in a REPL, right clicking on the image, then exiting caused a RuntimeError: Internal C++ object... error from ViewBoxMenu. I'd seen some errors like this in the gallery build, so after some digging, I found that wrapping these two lines in a try / except RuntimeError got rid of it and building the docs with PyQt5 and PyQt6 gives no errors:

pyqtgraph/pyqtgraph/graphicsItems/ViewBox/ViewBoxMenu.py

Lines 239 to 240 in 4b802de

    
           c = self.ctrl[i].linkCombo 
        
           current = c.currentText()

I'd need to understand a little better what's going on in ViewBoxMenu.setViewList (maybe some of the code after that should still run in some cases?), but this is promising.

I do still see a bunch of these types of errors with PySide:

Traceback (most recent call last):
  File "/home/krlyons/src/pyqtgraph/pyqtgraph/examples/DataSlicing.py", line 25, in <module>
    imv1 = pg.ImageView()
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/imageview/ImageView.py", line 129, in __init__
    self.ui.setupUi(self)
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/imageview/ImageViewTemplate_pyside6.py", line 42, in setupUi
    self.histogram = HistogramLUTWidget(self.layoutWidget)
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/widgets/HistogramLUTWidget.py", line 22, in __init__
    self.item = HistogramLUTItem(*args, **kargs)
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/graphicsItems/HistogramLUTItem.py", line 107, in __init__
    self.vb = ViewBox(parent=self)
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/graphicsItems/ViewBox/ViewBox.py", line 236, in __init__
    self.updateViewLists()
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/graphicsItems/ViewBox/ViewBox.py", line 1699, in updateViewLists
    nv = sorted(ViewBox.NamedViews.values(), key=view_key)
  File "/home/krlyons/src/pyqtgraph/doc/source/../../pyqtgraph/graphicsItems/ViewBox/ViewBox.py", line 1696, in view_key
    return (view.window() is self.window(), view.name)
RuntimeError: Internal C++ object (ViewBox) already deleted.

But I'm somewhat hopeful a similar fix could work and might end up getting rid of some of these errors that occasionally pop up in regular usage (or does that still actually happen?)

ixjlyons · 2022-06-05T19:01:41Z

Re: comment above

Yep, wrapping this in a try/except gets rid of the rest of the errors for PyQt and PySide

pyqtgraph/pyqtgraph/graphicsItems/ViewBox/ViewBox.py

Line 1689 in bb1b771

nv = sorted(ViewBox.NamedViews.values(), key=view_key)

The difference here is that from the traceback I pasted above, this is happening during setup and not teardown, so this is probably not the right approach. Maybe there's something in qtgallery to fix in this case.

j9ac9k · 2022-06-20T04:17:24Z

Hi @ixjlyons I just made some documentation changes which caused some merge conflicts, sorry about that!

Once addressed, would you mind re-running with error on warning enabled again? I'd like to try and replicate and solve those if possible!

ixjlyons · 2022-06-21T02:34:12Z

Updated with master and resolved conflicts. It's running now with fail_on_warning: true though those warnings are generated regardless.

The last thing I had done was play around with the environment to see if I could get all the OpenGL examples working reliably. I'm not really sure what's wrong but I do get some GL errors locally too.

For the record, here's are the patches I mentioned above that give me an error-free build locally (aside from the OpenGL stuff):

diff --git a/pyqtgraph/graphicsItems/ViewBox/ViewBox.py b/pyqtgraph/graphicsItems/ViewBox/ViewBox.py
index 3ca843ce..8454b26c 100644
--- a/pyqtgraph/graphicsItems/ViewBox/ViewBox.py
+++ b/pyqtgraph/graphicsItems/ViewBox/ViewBox.py
@@ -1693,7 +1693,10 @@ class ViewBox(GraphicsWidget):
             return (view.window() is self.window(), view.name)
 
         ## make a sorted list of all named views
-        nv = sorted(ViewBox.NamedViews.values(), key=view_key)
+        try:
+            nv = sorted(ViewBox.NamedViews.values(), key=view_key)
+        except RuntimeError:
+            return
 
         if self in nv:
             nv.remove(self)
diff --git a/pyqtgraph/graphicsItems/ViewBox/ViewBoxMenu.py b/pyqtgraph/graphicsItems/ViewBox/ViewBoxMenu.py
index cf468ed3..90bd6314 100644
--- a/pyqtgraph/graphicsItems/ViewBox/ViewBoxMenu.py
+++ b/pyqtgraph/graphicsItems/ViewBox/ViewBoxMenu.py
@@ -236,8 +236,11 @@ class ViewBoxMenu(QtWidgets.QMenu):
             self.viewMap[name] = v
             
         for i in [0,1]:
-            c = self.ctrl[i].linkCombo
-            current = c.currentText()
+            try:
+                c = self.ctrl[i].linkCombo
+                current = c.currentText()
+            except RuntimeError:
+                continue
             c.blockSignals(True)
             changed = True
             try:

doc/requirements.txt

j9ac9k · 2022-06-21T02:59:14Z

Heh, macOS seemed to have an issue 😆

Also some more issues on macOS:

Qt api: PySide2
WARNING: Could not find Xvfb

~~Qt api should definitely be PyQt6 here~~ (I'm an idiot, this was my own doing); also macOS does not have Xvfb, we probably should use it if we see it, but not try and force the issue if it is not present.

~~EDIT: the pyside2 bit may have been my mistake...working on sorting that out now.~~ was my mistake 😬

j9ac9k · 2022-06-21T03:22:01Z

this Runtime error that is being encountered is screaming race condition to me; I think it would be beneficial if we tracked down the source (whether it's in qtgallery or in pyqtgraph). I'll poke around some.

j9ac9k · 2022-06-21T03:39:58Z

Also after a make clean when I rerun I get this error:

WARNING: Duplicate example file name(s) found. Having duplicate file names will break some links. List of files: ['/Users/ogi/Developer/pyqtgraph/doc/source/../../pyqtgraph/examples/py2exe/plotTest.py']

Looking at our examples, looks like they are going in specific directories; we should probably rename those files here, since they're examples, I'm not too worried about going through a deprecation dance.

ixjlyons · 2022-06-21T03:40:07Z

Heh, macOS seemed to have an issue laughing

Hmm, not sure what to make of this. I suspect it's because QScreen.grabWindow supports grabbing contents that aren't part of the application - there's a note here about iOS at least.

The original motivation for using QScreen.grabWindow over QWidget.grab was to support QML applications in qtgallery. It may be worth reconsidering that switch or coming up with something better.

Also some more issues on macOS:
Qt api: PySide2
WARNING: Could not find Xvfb
also macOS does not have Xvfb, we probably should use it if we see it, but not try and force the issue if it is not present.

That's pretty much what is happening - it's a non-fatal warning.

However, I just noticed that disabling the virtual display, the renderings are mostly not the plot window contents but are seemingly random grabs of my display contents (behind the window?). Looking more at the grabWindow docs, there's a warning about X11, but it doesn't seem to be describing this situation exactly. Speaking of race condition...

this Runtime error that is being encountered is screaming race condition to me

Yep, haven't been able to track it down to this point.

doc/source/conf.py

j9ac9k · 2022-06-21T04:28:27Z

been poking around, in just about all cases, the ones that are raising errors are plots that have QTimers. I would guess what's happening is that the QTimer is still connected to the update methods, and that timer is still firing after qtgallery shuts down the QApplication. I'm trying to think of what would be a good way to "stop" the QTimer's in each of these examples before having qtgallery kill the QApplication instance.

j9ac9k · 2022-06-21T06:57:58Z

Hmm, not sure what to make of this. I suspect it's because QScreen.grabWindow supports grabbing contents that aren't part of the application - there's a note here about iOS at least.

I don't think this PR should attempt to address this issue. Was mostly bringing it up because it surprised me.

pyqtgraph/examples/MultiPlotWidget.py

+
+try:
+    from pyqtgraph.metaarray import *
+except:


pyqtgraph/examples/MultiPlotWidget.py

+from pyqtgraph.Qt import QtWidgets
+
+try:
+    from pyqtgraph.metaarray import *


ixjlyons · 2022-09-14T04:53:16Z

pyqtgraph/examples/MultiPlotWidget.py

@@ -0,0 +1,39 @@
+#!/usr/bin/python


TODO: re-remove this example, here and in the example list in _utils

ixjlyons added 2 commits February 11, 2022 21:38

Gallery mostly working

bcd0c87

- Add title to each example docstring - Add examples README - Sphinx conf is a total hack right now, need to figure out something better, potentially rename examples

Update to latest qtgallery, filter a few examples for now, use PyQt6

04653d6

Still seeing some "C++ object deleted..." errors, but at least with PyQt6, these seem to not be fatal.

ixjlyons marked this pull request as draft June 5, 2022 00:05

ixjlyons added 3 commits June 4, 2022 17:21

Switch to PyQt5 for now

0a92ebd

PyQt6 failed to install on readthedocs

Install xvfb on readthedocs

81b8855

Bring up to date with master

cc1e29f

ixjlyons commented Jun 5, 2022

View reviewed changes

pyqtgraph/__init__.py Outdated Show resolved Hide resolved

ixjlyons commented Jun 5, 2022

View reviewed changes

Enable intersphinx for links to API docs

4b421a4

ixjlyons added 5 commits June 5, 2022 12:03

Add glow example to run list. Enable GL examples

682f85a

Move copied default options to sphinx conf

3b0f9fb

Do an initial update for GLScatterPlotItem to work in gallery

dad3f78

Try installing opengl packages in rtd

7bc8382

Try with vispy xserver/xvfb args

fabf35f

Merge master in and resolve conflicts

b9c1ffd

j9ac9k reviewed Jun 21, 2022

View reviewed changes

doc/requirements.txt Outdated Show resolved Hide resolved

Merge fixup

928bd51

j9ac9k reviewed Jun 21, 2022

View reviewed changes

doc/source/conf.py Outdated Show resolved Hide resolved

Merge branch 'master' into docs-sphinx-gallery

d85f6ce

Merge branch 'master' into docs-sphinx-gallery

4463b93

github-advanced-security bot found potential problems Sep 14, 2022

View reviewed changes

Fix post-merge issues

58b047f

ixjlyons commented Sep 14, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add sphinx gallery to docs #2323

Add sphinx gallery to docs #2323

ixjlyons commented Jun 5, 2022 •

edited

ixjlyons Jun 5, 2022 •

edited

ixjlyons Jun 5, 2022

j9ac9k Jun 5, 2022

ixjlyons Jun 5, 2022

ixjlyons commented Jun 5, 2022 •

edited

ixjlyons commented Jun 5, 2022

j9ac9k commented Jun 20, 2022

ixjlyons commented Jun 21, 2022

j9ac9k commented Jun 21, 2022 •

edited

j9ac9k commented Jun 21, 2022

j9ac9k commented Jun 21, 2022

ixjlyons commented Jun 21, 2022

j9ac9k commented Jun 21, 2022

j9ac9k commented Jun 21, 2022

ixjlyons Sep 14, 2022 •

edited

Add sphinx gallery to docs #2323

Are you sure you want to change the base?

Add sphinx gallery to docs #2323

Conversation

ixjlyons commented Jun 5, 2022 • edited

ixjlyons Jun 5, 2022 • edited

Choose a reason for hiding this comment

ixjlyons Jun 5, 2022

Choose a reason for hiding this comment

j9ac9k Jun 5, 2022

Choose a reason for hiding this comment

ixjlyons Jun 5, 2022

Choose a reason for hiding this comment

ixjlyons commented Jun 5, 2022 • edited

ixjlyons commented Jun 5, 2022

j9ac9k commented Jun 20, 2022

ixjlyons commented Jun 21, 2022

j9ac9k commented Jun 21, 2022 • edited

j9ac9k commented Jun 21, 2022

j9ac9k commented Jun 21, 2022

ixjlyons commented Jun 21, 2022

j9ac9k commented Jun 21, 2022

j9ac9k commented Jun 21, 2022

ixjlyons Sep 14, 2022 • edited

Choose a reason for hiding this comment

ixjlyons commented Jun 5, 2022 •

edited

ixjlyons Jun 5, 2022 •

edited

ixjlyons commented Jun 5, 2022 •

edited

j9ac9k commented Jun 21, 2022 •

edited

ixjlyons Sep 14, 2022 •

edited