Add sphinx gallery #384
Add sphinx gallery #384
Conversation
|
One current issue is that some examples (e.g. the PBR render of the helmet) use models from |
|
Here is also a benchmark on how long the examples take to build on my machine. It doesn't look too bad: |
|
Adding this link here for future reference. It is possible to specify a custom static thumbnail image for a gallery example. This can be useful for gui-specific examples that we can't run on CI. For these, we can either run it offline and insert the thumbnail, or we could display a static image (eg the logo of the GUI backend used) for those examples. Here is the link to the relevant docs: https://sphinx-gallery.github.io/stable/configuration.html#providing-an-image-for-the-thumbnail-image |
|
I've reorganized this PR to make use of # sphinx_gallery_pygfx_<name> = <value>This builds on top of sphinx-gallery's mechanism, which takes the form of With this, we can easily control when to render. To create a render below a given example's code block one has to specify # sphinx_gallery_pygfx_render = TrueThis will trigger our scraper to check the global scope for a variable named # sphinx_gallery_pygfx_target_name = "<var_name>"
# eg.
# sphinx_gallery_pygfx_target_name = "disp"inside the block. The resulting variable is assumed to be a Display, Renderer, or Canvas, and is used to render the image to display. I've also added plumbing to procude animations/GIFs by (via I've also fixed the What is missing now is to set up lavapipe on the CI runners that build the docs (GH Actions and RTD). However, it should already be possible to build the gallery locally as part of the normal doc-building procedure. |
This is a bit weird. may need to track down where it comes from later
That said, we already improve over the default quality that comes out of GIF (and its 256 colors) 🥲
|
|
@Korijn Now we are using lossless compression, so any compression artifacts should disappear. This comes at the cost of additional runtime though, so we may need to revisit this once our examples or animation needs have grown to the limits of RTD build time. |
FirefoxMetzger
dismissed stale reviews from almarklein and Korijn
via
7e67e14
|
@Korijn I didn't get a notification that you resolved the conversation (GH doesn't seem to do those), so I missed that we can merge this until now. Master/Main has moved on, so I have re-synced the branch and resolved a merge conflict manually. Take a look and see if it still looks good :) From my side, we are still LGTM. |
|
@Korijn the validation tests broke because of a pathing issue after the |
|
Awesome work! |
|
And with that the gallery is live! Nice! |
|
Love the LSD backgrounds! 😆 |
Closes: #345 #145
This PR contributes a sphinx gallery that converts examples into a nice RST file including output renders. It also reorganizes the example folder into
introductory,feature_demo, andvalidationexamples to track them better and to display examples by category in the gallery.Note that this is a large PR. Most of the changes are fairly light-weight, though, so a lot of the touching lines are things like adding a title in the docstring or renaming an example. The critical pieces are in
conf.py(the sphinx config) and inutils/gallery_scraper.py.