search

VeinsOfTheEarth / RivGraph

Extracting and quantifying graphical representations of river and delta channel networks from binary masks
https://veinsoftheearth.github.io/RivGraph/
Other
81 stars 24 forks source link

Setup Docs Gallery #70

Closed elbeejay closed 2 years ago

elbeejay commented 2 years ago

Formatting for the docs gallery (#69) using sphinx-gallery. Example of how it should look is below. The example has some information on how to set up the .py files for the gallery and has an example of the thumbnail image and how to set things up in terms of the file structure.

To get this to work, I had us stop mocking all the RivGraph dependencies and actually install them for the documentation build. This means that now we can technically run the example notebooks every time we build the documentation rather than rendering the .rst files from the notebook output - do you think this is worth doing? We could set up the 2 examples in their own sphinx-gallery and they'd auto-run and be easily downloadable etc. Other things we can now do since we're installing all the dependencies for the docs build include having code snippets and examples in doc-strings that will render in the hosted API documentation. Happy to hear thoughts on adding example code to the doc-strings as well.

Feel free to push to this branch with modifications, or merge the PR and make changes after the fact - none of the work related to this effort should impact the source code.

image

image

jonschwenk commented 2 years ago

Dang, that was more involved than I expected! I'm not sure I grasp the implications of re-running the examples. I guess one benefit is that they'd be really easy to update (right now there might be a discrepancy between the jupyter notebooks and the docs). It might make it easier to add new examples (like the mouse brain). If the cost is just more build time, I don't think that's too heavy a price to pay. If it's a pain to port the examples as gallery items, maybe not worth it?

I like the concept of code snippets and examples in the API docs, but I'm not going to redo anything. It might be nice to have them for future docs, though.

I don't see a reason not to merge this. When doing a local doc build, will the gallery be re-built as well? I assume so.

Thanks for putting this together--looks great!

elbeejay commented 2 years ago

I guess one benefit is that they'd be really easy to update (right now there might be a discrepancy between the jupyter notebooks and the docs). It might make it easier to add new examples (like the mouse brain). If the cost is just more build time, I don't think that's too heavy a price to pay. If it's a pain to port the examples as gallery items, maybe not worth it?

I think that is the biggest advantage - you eliminate the possibility of your documented examples being out-of-date relative to the current version of the code, since the docs build will fail if you forget to update the example notebooks (as opposed to our hack-y solution now that is effectively static).

I don't see a reason not to merge this. When doing a local doc build, will the gallery be re-built as well? I assume so.

Yep, it regenerates the gallery every time the docs are compiled.

jonschwenk commented 2 years ago

I closed without merging before.