[ENH] Improved documentation

[mcencini]

I think documentation could use some lifting. I think Diataxis format is nice (e.g., mri-nufft). Besides the API, which is already included in the current documentation, we could re-structure the examples in a Sphinx-gallery and add the description of Pulseq format in the Explanation section. What do you think?

[schuenke]

Yeah, the documentation can definitely be improved. I will check out the mri-nufft docu later.

Together with @ckolbPTB, I started a (Py)Pulseq sequence repository, where we have an example notebook for every sequence. In the notebook, we create the sequence, simulate it using MRzero, export the data in MRD format, reconstruct it using our PyTorch MRI reco package MRpro and finally compare the results with the MRzero input data serving as a complete intergration test.

Here is an example for a quantitative single line IR SE sequence: https://ptb-mr.github.io/mrseq/t1_inv_rec_se_single_line.html

Using pre-commit, we ensure that all notebooks are added in a clean format.

In MRpro, we go one step further and only upload example scripts, which are automatically converted to notebooks in the CI pipeline, executed online and then embedded (with results) into the html docu. Here is an example for that: https://docs.mrpro.rocks/_notebooks/comparison_trajectory_calculators.html

It should be possible to implement this for PyPulseq as well, as we should be able to copy+paste most of the workflows directly.

[mcencini]

Very nice! Yes, that would be a great format for the example gallery. I would also prefer scripts.py converted to notebook.ipynb, rather than uploading notebooks directly - Sphinx Gallery also works this way, I do not have a strong preference on the practical implementation, so MRPro workflow would also be good.

Besides that, I think it would make sense discussing about how to organize the example gallery - a simple list of multiple sequences may be less useful than, for example, organize it in topics like "getting started", "registering events", "extensions: soft delay, rotation", "end-to-end: mrzero simulation + recon", "external pulses: arbitrary waveforms" etc. What do you think?