Jupyter to Marimo and Sphinx documentation migration

[ViniciusTxc3]

Migration of user-guide notebooks from Jupyter (.ipynb) to Marimo (.py) with Sphinx integration, including process, image placement, current difficulties, and build-time impact.

---

1. Migration process (overview)

Current state (before full migration)

• Docs: Sphinx with myst-nb for Jupyter notebooks.
• Notebooks: Many .ipynb files under docs/user_guide (tutorials, examples, fluid-flow).
• Index: MyST user_guide.md with {toctree} pointing to notebook names.

Target state

• Notebooks: Marimo .py files in docs/user_guide.
• Integration: sphinx-marimo to embed interactive notebooks (HTML/WASM) in the built site.
• Pages: One .rst file per notebook using the .. marimo:: directive; user_guide.md (or a main RST) references these pages.

Steps (high level)

1. Install: marimo, sphinx-marimo; add them to docs/requirements.txt.
2. Convert: Run marimo convert <file>.ipynb -o <file>.py (per file or in batch via Bash/PowerShell).
3. Sphinx config: In docs/conf.py, add sphinx_marimo to extensions and set marimo_notebook_dir, marimo_default_height, etc. Optionally remove or keep myst_nb during transition.
4. Per-notebook RST: For each migrated notebook, add a .rst in docs/user_guide/ that embeds the .py with .. marimo:: user_guide/<name>.py (and optional :height:, etc.).
5. ToC: Update docs/user_guide/user_guide.md (or equivalent) so the toctree points to the new RST pages (e.g. tutorial_part_1, example_1, …).
6. Post-install patch: After installing sphinx-marimo, run python docs/tools/patch_sphinx_marimo_show_code.py so embedded notebooks show code by default (--show-code in the export).
7. Validation: marimo check (and optionally marimo edit) on the .py files; then make html in docs/ and manual check of the built site.
8. Dependencies: Prefer uv for installing deps and building; see docs/Makefile (install-deps, make html).

Already migrated content lives in docs/user_guide/: multiple tutorial_part_*.py / example_*.py / fluid_flow_*.py and corresponding .rst files.

---

2. Current migration difficulties

• WASM / Pyodide limitations: sphinx-marimo exports notebooks to HTML/WASM run in the browser via Pyodide. Many Python packages (including ross and some versions of numpy/scipy) are not available or not fully supported in Pyodide. Notebooks that depend on ross or heavy scientific stack may fail in the browser with ModuleNotFoundError or “An ancestor raised an exception”.
• Workaround in notebooks: The migration guide and existing examples (e.g. docs/user_guide/example_1.py) use a pattern: try/except ModuleNotFoundError for ross/plotly, set a flag (e.g. _deps_ok), and in dependent cells show a message (e.g. via mo.md()) that the notebook should be run locally (uv run marimo edit docs/user_guide/...) when deps are missing in the browser. This keeps the doc build and WASM view from breaking while still allowing full execution locally.
• Reactive execution: Marimo is reactive; execution order is driven by dataflow. Notebooks that rely on manual cell order or shared mutable state may need refactoring after conversion from Jupyter.
• Patch for “show code”: The installed sphinx-marimo package does not pass --show-code to marimo export html-wasm by default. The project uses a one-time script docs/tools/patch_sphinx_marimo_show_code.py after pip install sphinx-marimo; this must be run again if the package is reinstalled or upgraded, and may need to be updated if the upstream builder code changes.
• Hybrid strategy: The migration doc suggests a hybrid approach: use Marimo for simpler/conceptual notebooks and keep myst-nb for notebooks that heavily use ross or other Pyodide-incompatible libraries. That implies maintaining two code paths (Marimo vs Jupyter) and clear conventions for which notebooks are “Marimo-only” vs “Jupyter-only” in the built docs.

---

3. Build time / compilation slowness for the final site

• Cause: During make html (or sphinx-build), sphinx-marimo runs marimo export html-wasm for each notebook referenced by a .. marimo:: directive. Each export compiles the notebook and produces HTML/WASM assets; this is significantly heavier than only rendering RST/MyST or static Jupyter outputs.
• Effect: Full documentation builds are noticeably slower than before the migration, especially with many notebooks. The built output under docs/_build/html/ includes _static/marimo/ and cache under _build/.marimo_cache/.
• Mitigations to consider (for future work):
  • Use marimo_click_to_load (e.g. "compact") so notebooks load on demand instead of all at once, which can reduce perceived load time in the browser; it does not reduce Sphinx build time.
  • Limit the number of notebooks embedded on a single page.
  • Ensure CI/docs jobs have enough resources and time; document expected build duration.
  • Optionally cache or reuse marimo export outputs when source .py files have not changed (would require custom Sphinx or script logic).

---

4. References

• Docs layout: docs/conf.py, docs/Makefile, docs/user_guide/user_guide.md, docs/tools/patch_sphinx_marimo_show_code.py.
• External: Marimo docs, sphinx-marimo, Pyodide packages.

---

The PR #1266 implements these changes.