Move examples to sphinx-gallery #57
Conversation
|
Also, it looks like there are a ton of images in the |
|
It appears the builds are failing because you all upload to PyPI on every build (and I don't have privileges to do that)? |
There was a problem hiding this comment.
Hey there! Sorry for being a bit late on this, but:
THIS IS AWESOME
Thanks for your effort. I just have a few comments:
- There are warnings from Matplotlib given as output in the generated files. We can suppress them with:
import warnings
warnings.filterwarnings(
"ignore",
category=UserWarning,
message='Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.',
)See: https://sphinx-gallery.github.io/stable/configuration.html
2. The Herten example takes really long... I don't know if we can somehow speed that up.. but it is working for now, so I am fine with it.
3. I would put the "introduction" at the end and call it "Miscellaneous"
4. tutorial 2 has a strange structuring. I would make some more sub-items
5. I would swap the two sub-items under tutorial 3
6. tutorial 4 could be just one page
Some more comments were made in the review.
I will update the actual examples itself after merging this PR.
Thank you for the effort! You are the contributor of the month :-)
| "examples/06_conditioned_fields/", | ||
| "examples/07_transformations/", | ||
| ], | ||
| # Patter to search for example files |
| "backreferences_dir": None, | ||
| # Modules for which function level galleries are created. In | ||
| "doc_module": "gstools", | ||
| #"image_scrapers": ('pyvista', 'matplotlib'), |
There was a problem hiding this comment.
For when you all start using PyVista for some 3D viz in the example gallery, you will need to add the pyvista image scraper. I figured I would leave this here for when that happens
| .. toctree:: | ||
| :maxdepth: 1 | ||
| :includehidden: | ||
| :maxdepth: 3 |
There was a problem hiding this comment.
Why :maxdepth: 3? We think 1 is enough, as the chapters are very short in general.
These changes moves all of the examples to work with Sphinx Gallery (SG). SG provides a way to show off your examples with really nice formatting and incorporating the examples as test cases to make sure the example in your docs are always in working state when a user tries them out.
Previously, the examples were in two places, in scripts under the
examplesdirectory and in code blocks within the documentation pages. Having the examples in two places can lead to discrepancies and maintenance issues, these changes consolidate the examples into a single place (doc and code) and provide a way to test all of the examples.I would highly recommend that you all switch from readthedocs.org to Travis and GitHub pages for building and deploying your docs. Readthedocs build environment is very limited and you will not be able to showcase any 3D examples with PyVista if you stay on readthedocs. Also, the whole purpose of this is to have your examples all in one place where they can be tested and incorporated into the documentation - Sphinx-gallery will run each example when building the docs and that is a great build status check to incorporate in with GitHub status checks (readthedocs does not support that)