Sphinx gallery

[banesullivan]

Continuation of #57 as there was a branching issue. Now this should properly have develop set as the base. See #57 for details and be sure to "squash and merge" on GitHub these changes

[MuellerSeb]

Oh no! I reviewed the wrong PR!

[MuellerSeb]

@LSchueler will do the review later this day. But just a short compliment: THIS IS F+++ING AWESOME. :-)

[LSchueler]

Copy pasta from PR #57:

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.
We will update the actual examples itself after merging this PR.

Thank you for the effort! You are the contributor of the quarter :-)

[banesullivan]

Also, the examples generate some temp files like field.vtu and field.vtr. Would it make sense to add *.vtr and *.vtu to the .gitignore, or do you all have some data files that are tracked?

[banesullivan]

Also, when installing locally, the gstools/variogram/estimator.cpp file is generated. should this be ignored?

[MuellerSeb]

I vote for ignoring *.cpp *.vtu, *.vtr and so on.

[MuellerSeb]

On other thing: Could you add a short guide on what an example should look like to the CONTRIBUTING.md? This would be also good for us to know how to add examples the right way ;-)

[banesullivan]

1. warnings

Done.

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.

I'm going to leave this as is and let you all modify the examples since I don't know everything that is going on in gstools

3. I would put the "introduction" at the end and call it "Miscellaneous"

Done. I kept it with the 00 prefix as you wont want to rename it eveertime a new tutorial is added. But it will be shown last in the docs.

4. tutorial 2 has a strange structuring. I would make some more sub-items

Would it make more sense for you all to organize the examples? I still barely understand everything going on in gstools so you all probably have better insight into how it should be structured.

5. I would swap the two sub-items under tutorial 3

Like swap order? If so, done.

6. tutorial 4 could be just one page

Hm. Would you want to add more scripts to this tutorial down the road?

[banesullivan]

On other thing: Could you add a short guide on what an example should look like to the CONTRIBUTING.md? This would be also good for us to know how to add examples the right way ;-)

Yeah, definitely! This might take me a bit to geet around to...

[MuellerSeb]

@banesullivan : Just add a short sentence like:

If possible add an example showing your new feature to one of the examples sub-folders.
Follow this .... guide so it is compatible with sphinx-gallery.

That would be enough I think.

And you can leave the examples as they are now. I will have a look at them afterwards for polishing.

Thanks again mate!

[MuellerSeb]

And a strange thing is, that the warnings are still shown in my local build...

Edit: Sorry, false alarm. Had to remove the generated examples folder before rebuilding the docs.

[LSchueler]

Just one tiny typo, but I think then all your awesome eye candy can finally be merged!

[MuellerSeb]

Looks fine now.