WIP: docs: Use sphinx-gallery - #270
Conversation
This PR only introduces the infrastructure and an eventseg example. The rest of the examples will need to be converted in future PRs. Note that the README files have to have the "txt" extension and the RST titles within have to be formatted hierarchically at least for the first two levels (`examples` and its subdirectories) so they are displayed properly in the resulting HTML. Fixes brainiak#268.
|
@cbaldassano, what do you think about the Sphinx-Gallery idea of creating notebooks from Python files? |
|
This looks nice, and it would be great to have the example plots in with the documentation. It would be nice workflow-wise if this was able to take notebooks as input - or have a system that converts notebooks to python files with their syntax, and then passes them to sphinx-gallery. Is that possible? |
|
Good point about the workflow. I'll look for such a converter. |
|
@cbaldassano, it looks like a converter is not coming to Sphinx-Gallery anytime soon for reasons explained on their issue tracker: However, the following script (linked in the issue above) should give reasonable output in my brief experience: I can add a link to the script above to the contributors guide. What do you think? |
|
Yep that looks good to me. The issues they discuss (incompatibilities with Markdown and magic functions) shouldn't be a big problem. Looking at the eventseg/HiddenMarkovModels.ipynb notebook, some potential problems could be: The biggest of these is the reliance on external data. Should we only use sphinx-gallery for self-contained examples? |
|
I think we can include external data as long as we do the downloading in Python. This can be as simple as However, run time can be a problem. As we integrate more examples, I think we should create a new make target for building the examples, which should not be called by default. This will take care of another problem I foresee: dependency bloat for development requirements. Right now, each example directory has its own requirements file, but if we build the examples by default, we need to centralize the requirements. |
|
Closing this PR. We still have issue #268 to continue the conversation. I think we should use a solution that works directly with Jupyter notebooks, without converters, such as nbsphinx: |
This PR only introduces the infrastructure and an eventseg example.
The rest of the examples will need to be converted in future PRs.
Note that the README files have to have the "txt" extension and the
RST titles within have to be formatted hierarchically at least for the
first two levels (
examplesand its subdirectories) so they aredisplayed properly in the resulting HTML.
Fixes #268.