Quickstart Guide and MyST-NB implementation

[reint-fischer]

Implementing MyST-NB as a sphinx extension will replace both nbsphinx and myst_parser. This way, we can read and execute both .md and .ipynb notebooks, which will allow us to write new notebooks in .md for better integration with the rest of the documentation.

TODO

• add myst_nb remove myst_parser
• transfer .ipynb execution from nbspinx to myst_nb
• Execute quickstart tutorial on docs build
• Check notebook testing in CI
• Fix User Guide links
• Check notebook outputs in dark mode
• Finish writing quickstart tutorial as .md notebook

Fixes #2335

[reint-fischer]

I managed to build the docs using MyST-NB and I think the docs look pretty good, which I think is exciting! The main observations I have so far:

• building the docs already took a couple of minutes with only 5 notebooks, but that was only the first time. Notebooks are only executed if they have changed so once I am only working on the quickstart tutorial it is pretty much as quick as before.
• writing new notebooks is more challenging because I cannot execute the cells in VS Code as I am editing them. There might be a way to do this?
• I still need to look into the printing of outputs, such as the progressbar and with the docs in “dark mode"

[VeckoTheGecko]

• writing new notebooks is more challenging because I cannot execute the cells in VS Code as I am editing them. There might be a way to do this?

Sorry - slightly confused with the terminology - by 'notebook' do you mean actual notebook (ipynb extension) or markdown file with executable cells

[reint-fischer]

• writing new notebooks is more challenging because I cannot execute the cells in VS Code as I am editing them. There might be a way to do this?

Sorry - slightly confused with the terminology - by 'notebook' do you mean actual notebook (ipynb extension) or markdown file with executable cells

Yes, I meant the markdown file with executable cells. I have written the quickstart tutorial in this format and I like writing in markdown, but I have still written it much like I would write a Jupyter Notebook. I like the consistency and integration with the rest of the documentation website, but it is helpful to be able to execute the cells as I am writing them to see that the result is as I expect, which is a Pro for Jupyter Notebooks.

[reint-fischer]

Noting that:

• thumbnail gallery support in MyST-NB is a long-standing open issue: Enable thumbnail galleries of notebooks executablebooks/MyST-NB#396
• dark mode support is being worked on: Improve theme integration executablebooks/MyST-NB#693

[erikvansebille]

Perhaps also change the name of this PR to better reflect what it is (the QuickStart guide and the myST-nb implementation)?

[VeckoTheGecko]

Maybe I missed the discussion - why the verbose_progress=False?

[VeckoTheGecko]

What do you think about hard wrapping of prose in markdown files @reint-fischer ? Is that also something to mention here?

(e.g.)

I can write a whole paragraph on one line, but it becomes a bit difficult to read when suggesting edits via GitHub, or depending on your editor settings. When rendered in the docs site, it doesn't matter if this is spread along multiple lines (as long as there is no blank line in between). If you roughly spread it across multiple lines then working with diffs becomes easier.

I can write a whole paragraph on one line, but it becomes a bit 
difficult to read when suggesting edits via GitHub, or depending 
on your editor settings. When rendered in the docs site, it 
doesn't matter if this is spread along multiple lines (as long 
as there is no blank line in between). If you roughly spread it 
across multiple lines then working with diffs becomes easier.

We could go to the extreme and enable this via a pre-commit hook, but that would be quite messy and unnecessary I think

[reint-fischer]

Yeah I am not opposed to that, I can add a recommendation; is there a specific length you like?

Parcels/docs/development/docsguide.md

Line 44 in 3c9447a

- We recommend hard wrapping prose in markdown so that reading it becomes easier in any editor.

[VeckoTheGecko]

90ish

[reint-fischer]

After editing a few files I am a bit more skeptical; adding and removing wrapping for entire paragraphs seems quite cumbersome.

[VeckoTheGecko]

That's fair - maybe just something to be aware of that you can hard wrap items if you want to and it wont change rendering in the final markdown. Doesn't have to be a hard style guide. Feel free to mention it how you want in the style guide, or not at all - that's fine too

[reint-fischer]

Maybe I missed the discussion - why the verbose_progress=False?

Thanks for bringing this up, it was a temporary fix for the way MyST-NB currently outputs the progressbar, but I found that hiding the cell outputs is a better solution. I had already managed to do this for the .md notebooks, but have now also implemented it for the .ipynb notebooks.

[erikvansebille]

🥳