Examples file format

[jhillairet]

Currently only a few numbers of examples are available in markdown format and processed to generate the documentation, while many more examples (.py files) actually exist in the repo.

I guess that converting python example files to markdown format takes some time, and leads to duplication for maintenance. So I was wondering if using Jupyter notebooks directly for the documentation have been considered before? It's easy to use sphinx to convert notebooks into html (no duplicate .py/.md file), and also convenient to integrate figures and equations.

Sure, it's less convenient for tracking changes with git (but doable. Also new formats are emerging, like quarto, etc).

[milanofthe]

@jhillairet yes, @RemDelaporteMathurin suggested something like that using jupyterbook similar to the FESTIM docs. The current state of the docs is my first shot and I also think adding more examples and building it in a systematic way would benefit it. At some point Id like to redo the docs if I find some time or get some help :)

[RemDelaporteMathurin]

@jhillairet I would suggest using jupyter-book as Milan said, that way we can write markdown files (with the myst format) and the code is executed when compiling the HTML. Then each page/demo can be downloaded as a python file, or notebook:

[RemDelaporteMathurin]

However I don't know if this should be a separate book or if it should integrate with the current documentation with API reference etc.

[jhillairet]

I personally like when the API info is close to examples/tutorials (the latter can have links to the API too, convenient). I'll look into jupyter-book.

[RemDelaporteMathurin]

jupyterbook supports RST files: https://jupyterbook.org/en/stable/file-types/restructuredtext.html