sphinx gallery

[clewis7]

start #486 for hopefully the last time :)

According to @almarklein, should just be able to directly use pygfx image scraper

Initially, I am just trying to get it to work with one set of the desktop examples.

Current issues:

1. Offscreen rendering is being ignored even if it is in os.environ keys, should have maybe been fixed by Improvements to GUI selection and Qt support #431
2. When using gflw WgpuCanvas, the pygfx scraper is looking for the canvas or renderer and then attempting to call canvas.draw() but the desired method is canvas.draw_frame()
3. Beyond this, if I in-place change the source code of the pygfx scraper to use the correct draw method, an issue arises with trying to write a frame:

    Traceback (most recent call last):
      File "/home/caitlin/venvs/fpl/lib/python3.12/site-packages/sphinx_gallery/scrapers.py", line 341, in save_figures
        rst = scraper(block, block_vars, gallery_conf)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/caitlin/venvs/fpl/lib/python3.12/site-packages/pygfx/utils/gallery_scraper.py", line 136, in pygfx_scraper
        render_screenshot(canvas, namespace, img_filename, **config)
      File "/home/caitlin/venvs/fpl/lib/python3.12/site-packages/pygfx/utils/gallery_scraper.py", line 209, in render_screenshot
        iio.imwrite(
      File "/home/caitlin/venvs/fpl/lib/python3.12/site-packages/imageio/v3.py", line 147, in imwrite
        encoded = img_file.write(image, **kwargs)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/caitlin/venvs/fpl/lib/python3.12/site-packages/imageio/plugins/pillow.py", line 443, in write
        for frame in ndimage:
    TypeError: iteration over a 0-d array

@kushalkolar @almarklein thoughts?

[clewis7]

Can now force offscreen rendering, so the gallery is being generated.

Current issue is figuring out how to format the index.rst and conf.py in order to properly display the gallery.

1. For some reason the dropdown for all the examples only gets placed on the last one
   
2. The thumbnails are being displayed weird
   

[clewis7]

@BalzaniEdoardo

[BalzaniEdoardo]

@clewis7 remove the "nbsphinx", it seems to create some conflicts

sphinx-gallery/sphinx-gallery#1195

[BalzaniEdoardo]

this solves the refs not being generated

[clewis7]

@kushalkolar Like Edo said, in order to use sphinx-gallery we would need to remove nbsphinx. Pitfall of this is that then the quickstart.ipynb will not render...

[kushalkolar]

That's ok, specific examples are more important.

[kushalkolar]

This is great 😄 !

Some things:

Can you pre-download the images in conf.py so we dont get this:

Also need to figure out how to properly set the canvas size so that when the screenshots are taken we don't have that huge blank space.

Can you check how we can have animated examples, like pygfx: https://pygfx.com/stable/_gallery/introductory/cube.html#sphx-glr-gallery-introductory-cube-py

We can show some of the animations from quickstart, and I guess if you tag it with "test_examples = false" it will generate sphinx gallery docs with that example but not use it for the test suite? Since we don't want animation examples to run with screenshot tests (at least not yet, maybe later 😄 )

[kushalkolar]

More:

For each example, specify that the if __name__ == "__main__" is NOT how it's supposed to be done for interactive use. We should make a doc page on interactive use in ipython and jupyter using this: https://wgpu-py.readthedocs.io/en/stable/gui.html#using-wgpu-interactively

Users should never call fpl.run() for interactive use.

[kushalkolar]

specifiy that this line isn't required for users, or see if there's a way for the pygfx scraper to look for fig.canvas instead of canvas?

in all examples

[clewis7]

I think perhaps we can use figure instead...

pygfx scraper looks for one of ["renderer", "canvas"] to be defined, but will also look through proxy objects such as "figure", "display", "disp", "plot"

So I will try that

[clewis7]

I tried changing fig to figure so then the scraper would look for figure.canvas...but then writing the thumbnails failed

[clewis7]

I think for now, we should just to canvas = fig.canvas and have a note saying that it is not required for users and after FENS I can look into fixing them

[clewis7]

NOTE:
sphinx-gallery doesn't have the namespace __file__, so in the scatter/ examples will need to change how the path to the iris.npy data is loaded so that gallery can be generated properly and tests will still run without using __file__ or os.getcwd()

[clewis7]

TODO:

• fix canvas size so thumbnails/images don't have large white space
• add more animation examples

[kushalkolar]

After this I propose:

1. get rid of quickstart.ipynb, replace with a guide in the docs
2. get rid of any example nbs that are in the examples gallery, except for the selector tools?
3. what about moving all example nbs to the examples gallery and having just a few example nbs? Like ImageWidget, selector tools, and maybe one simple one that shows layouting with VBox/HBox and a few graphics?

[clewis7]

After this I propose:

1. get rid of quickstart.ipynb, replace with a guide in the docs
2. get rid of any example nbs that are in the examples gallery, except for the selector tools?
3. what about moving all example nbs to the examples gallery and having just a few example nbs? Like ImageWidget, selector tools, and maybe one simple one that shows layouting with VBox/HBox and a few graphics?

This sounds good to me, and doable before FENS

[kushalkolar]

A few event examples too, click event that changes colors of closest circle, and another example where changing a feature prints the event attributes and event.info.

[clewis7]

I added a simple event example but I am going to hold off adding any more examples until we merge this with graphic features PR

[clewis7]

@kushalkolar merged main and updated...should be ready for review :D

[kushalkolar]

make a section, perhaps in the guide, on using fpl interactively in jupyter lab and ipython, the wgpu docs might provide some inspiration: https://wgpu-py.readthedocs.io/en/stable/gui.html#using-wgpu-interactively

but basically, there is %gui qt and in jupyterlab or ipython they can also do fig = fpl.Figure(canvas="glfw") to use glfw

[clewis7]

#510

[kushalkolar]

This example seems like it's missing from the gallery 🤔 https://github.com/fastplotlib/fastplotlib/blob/main/examples/desktop/line_collection/line_stack_3d.py

[clewis7]

This example seems like it's missing from the gallery 🤔 https://github.com/fastplotlib/fastplotlib/blob/main/examples/desktop/line_collection/line_stack_3d.py

ahhh, wasn't rendering properly because of the canvas size

I found that the canvas size needs to be (700, 560)...sphinx-gallery likes that best

[clewis7]

yayyyy! @kushalkolar