Skip to content

Modifications to use sphinx gallery for the tutorials.#1

Open
TeresiaOlsson wants to merge 3 commits into
mainfrom
notebooks-sphinx-gallery
Open

Modifications to use sphinx gallery for the tutorials.#1
TeresiaOlsson wants to merge 3 commits into
mainfrom
notebooks-sphinx-gallery

Conversation

@TeresiaOlsson

@TeresiaOlsson TeresiaOlsson commented Jul 24, 2026

Copy link
Copy Markdown
Member

This is an example for how to use sphinx gallery for the tutorials.

I think it looks very nice and gives both the option to download files and run them interactively with binder. It follows this: https://sphinx-gallery.github.io/stable/auto_examples/index.html

Downsides are:

  • Some parts of the tutorials needs to use rst syntax instead of markdown.
  • Sphinx gallery generates notebooks from python files. It can't use notebooks directly. So someone writing a tutorial need to first write the notebooks to test, then export to a py file and make some manual modifications to change markdown to rst.

However, py files are better for version control than notebooks.

It looks like this if you don't want to build locally or download the artifact from the workflow to be able to see it.

image image

@GamelinAl

Copy link
Copy Markdown
Member

A few issues:

  • For interactive use, we will depend on a service provider. For example, at the time I write this binder does not work.
  • This requires to learn a new way to make documentation (.py + .rst), to in the end, have a notebook like appearance.

Other than this, it can be a good idea. And for sure it's much better for version control to have .py files than .ipynb files.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants