[vineetbansal]

Closes #331

I'm going through the tutorial notebooks in sequence carefully to make sure they're not advertising concepts that have been superseded by newer code in dev, plus any other minor issues I see.

Builds on top of any PRs < 336, so those should be reviewed/merged first, and this one rebased on dev for a cleaner review.

This PR will also eventually cover any new sections we want to add to these tutorials (including EventGraph or HigherOrderGraph.

[vineetbansal]

@M-Lampert - I've had several extended sessions with Claude and have merged all the documentation (existing as well the ones we got from polnets-tutorials. I've also added 2 new tutorials on EventGraph and HigherOrderGraph respectively. This PR now implements the basic layout you came up with in issue #331, with minor changes.

Admittedly, after the tweaks for the basic notebooks (now under a "Getting Started" menu item) that I did go through manually, I haven't gone through the advanced tutorials manually at all. All I've honestly done is to ensure that they render without any errors (w.r.t the existing and upcoming changes to the dev branch), and that they've been verified for accuracy and lack of redundancy by both Opus and Fable.

Since this PR adds a whole bunch of infrastructure changes to the doc generation in the CI, namely:

• Switched to raw .py files (Marimo notebooks)
• The .ipynb files corresponding to these .py files are pre-generated and shipped right alongside the .py files (because some of them take a while to run, we don't want to run them on the CI).
• The CI for the docs does check that the .py/.ipynb are in sync by running a helper script (uv run python docs/export_tutorials.py --check). This check ensures that the notebook code cells are the same as the corresponding .py files, not that they've actually been run (though for teaching purposes we'd want to pre-execute the notebooks locally using uv run python docs/export_tutorials.py so that their final output is shipped along with the notebooks).
• The CI runs a static check (no execution) on the notebook scripts using marimo check .. (checks circular dependencies of cells etc. without actually running them)
• The CI does run python /path/to/marimo/script.py on all but a handful of super-time-consuming notebooks (manim_tutorial.py and graph_learnings/gcns.py).
• Docs for the main branch and the dev branch are built independently, and the live site will show the main docs (unchanged in all the work we've done in the past few months).
• The dev branch docs can be viewed by clicking on its entry in the dropdown. Screenshot from a local deployment below:

I'm wondering if we should merge this PR first (pending any workflow changes that you suggest, which I'm happy to make) and then check the docs on the "live" site for manual review? This will allow us to separate any bugs in the docs generation process with wording changes needed in the docs themselves.

[M-Lampert]

This looks great! Thank you for sorting all of this out.

Just to confirm that I understood the organisation and the workflow correctly: We've switched to Marimo notebooks, which are basically Python files. Editing the notebooks needs to be done in these Marimo notebooks, which work well with version control. We still have Jupyter notebooks for displaying the notebooks on the documentation website. These notebooks need to be re-exported manually from the Marimo notebooks whenever we make any changes to the notebooks or the source code that would change the output of any of the notebooks. To make sure that at least the code in the notebooks is in sync, we have a CI test that checks if the code in the Python files is the same as the one in the Jupyter code cells.

Did I get the workflow right? If I understood everything correctly, then everything looks good to me, and I only have one minor suggestion before we can merge this: Can we move the Jupyter files into a separate subdirectory inside each tutorial subdirectory called something like _notebooks or something similar? That would make the file organisation a bit easier if you only see the Marimo notebooks at first glance, and it would also hopefully discourage making changes to the Jupyter notebooks directly.

[vineetbansal]

@M-Lampert - yes, all your observations are correct. Normally we would just do everything in the Marimo world, but since we're using pytorch which pyodide does not support yet, we can't export the tutorials to plain html for the documentation website, and also the marimo <-> mkdocs integration doesn't seem mature to me (going by their activity). That can be a future task.

Great point about separating notebooks into a _notebooks folder so developers are less inclined to modify those directly (though the CI will fail in that case like you observed). Let me do that now.

[M-Lampert]

Thanks! Feel free to merge once that is done.