docs: improve introductory tutorial

[puer-robustus]

This fixes

• some minor grammatical errors,
• an incorrect header indentation level,

and also starts using the standard markdown footnote syntax. Since the latter is a bit of a bigger change (footnotes go to the end of the page), I put it in a separate commit. We could also consider using footnotes for the two scientific quotations, if so desired.

[EwoutH]

Thanks, good catches!

Can this PR be merged or do you want to make other changes?

[puer-robustus]

Depends on what your take on the two scientific references in the intro is. I have no strong preference (footnotes vs. keeping as is) either way.

[EwoutH]

Is this working as expected?

References as footnotes that refer to the full source at the bottom of the page sounds good.

[puer-robustus]

Hmm, no, actually I'd have expected something like that:

As far as I can tell, this is also what it looks like in the readthedocs build for the PR.

[EwoutH]

Yes, that's nice. Can we create a solution that also looks nice in the Jupyter notebook?

[puer-robustus]

Only by adding the jupyterlab_myst dependency to the jupyter executable with which you're opening the .ipynb file. Then the footnote will look like this:

The footnote text will only show up by hovering over the [2] link in the example above.

[EwoutH]

Maybe in that case I prefer a direct link to the papers (just [text](url)).

[puer-robustus]

Maybe in that case I prefer a direct link to the papers (just [text](url)).

That's a good idea for the papers: will adapt the tutorial accordingly.

What about the footnotes detailing the Grids and providing background info on pandas? Do we keep them as they are now (*) or with the footnote syntax introduced in this PR (nicer docs website but slightly more convoluted notebook looks)?

[EwoutH]

Both ways are fine I think, I slightly prefer the readability of the notebooks over the docs, since they are mainly interactive tutorials.

[puer-robustus]

I've removed the footnote syntax changes (but kept some formatting corrections in the footnote text).

Maybe in that case I prefer a direct link to the papers (just text).

I've reconsidered here: Do we really want to do that? I think a reference as it currently stands is not so bad and provides more info than a simple URL could. I'd suggest to just keep those citations as is today.

[puer-robustus]

@EwoutH Is there anything else you'd want me to change to get this merged?

[EwoutH]

Looks good, thanks!