MkDocs/Sphinx integration (a la `mknotebooks`)

[patrick-kidger]

Description

A very frequent use case for notebooks is to writing examples for software libraries.

Pulling an example from one of my own libraries, this example is produced by creating it in a Jupyter notebook, and then using mknotebooks to convert it into a MkDocs-compatible webpage.

Anecodatally, most other Python software I see generates substantial portions of their own documentation in the same way.

Now conveniently, Marimo already supports export to HTML! The only thing that is missing is the ability to make this part of documentation generation.

The main two documentation generators seem to MkDocs + mkdocs-material (usually newer software libraries) or Sphinx (usually older software libraries).

It'd be awesome if there was a tool similar to mknotebooks (or whatever Sphinx uses that's similar) to ease adopting Marimo for such use-cases.

Suggested solution

-

Alternative

Continue to use Jupyter instead of Marimo.

Additional context

No response

[dmadisetti]

Nice! I use mkdocs-jupyter. But marimo with mkdocs is something I've been playing around with for a second.

So just pushed what I have locally up:

• very messy, just playing around: https://github.com/dmadisetti/mkmarimo
• utilizing the quarto base: https://github.com/dmadisetti/quarto-marimo to increase code reusage.

I know this is definitely in marimo's plans to make notebooks more portable. I'm a full time PhD student, but here' the timeline as I see contributing to marimo:

1. Polish off and migrate the quarto/ pandoc plugin to marimo-team/mo-quarto for embedded markdown exports
   • Using this with my own notebooks, but ideally should be in a place to share with others
2. Get native save / caching working
   • I'd like to have some pretty heavy notebooks in a sharable form. Leveraging aggressive caching or save outputs means that compute heavy notebooks can be quickly executed, and still technically having the notebook run in browser, and make it interactive.

3. Polish and publish the MkDocs plugin

   • MkDocs is also my preference of choice, but having quarto means that it can potentially be embedded anywhere.

   Some action items that have already been crossed off!

   • native markdown format (e.g. https://github.com/marimo-team/marimo/blob/main/marimo/_tutorials/markdown_format.md)

   Relevant issue (your choice to mark as dupe):

   • https://github.com/marimo-team/marimo/issues/1882

   Also publishing to Observable:

   • https://github.com/marimo-team/marimo/discussions/962

[mscolnick]

FYI: We, alongside a few contributors, are working on a mkdocs plugin.

ETA: 2 weeks (hopefully)

[AdamRJensen]

Note, Jupyterbooks are built using Sphinx and Sphinx seems to be more extensible than MkDocs which would be one argument for heading the Sphinx way.

[Haleshot]

Wanted to drop by to post the marimo-mkdocs plugin repo here - https://github.com/marimo-team/mkdocs-marimo CC: @patrick-kidger

[patrick-kidger]

Oh, super interesting! Thank you.

I've just taken a look at it -- if I understand correctly this isn't a way to transform a Marimo notebook, but is essentially a competing serialization format to the current .py files? (It's still executable, just now it's in .md format instead.)

I'm guessing the reactivity comes with some heavy extra extensions. I expect static web pages to be my 99% use-case -- if I set is_reactive: false will these not be loaded?

[Haleshot]

I'm guessing the reactivity comes with some heavy extra extensions. I expect static web pages to be my 99% use-case -- if I set is_reactive: false will these not be loaded?

From this link - https://marimo-team.github.io/mkdocs-marimo/getting-started/configuration/#code-fence-options, it shows how setting is_reactive=false just shows a static output:

By default is_reactive=true. If your primary usecase involves graphs/plots/visualizations to be static, setting this parameter to be false would make sense.

[mscolnick]

As @Haleshot mentioned, we've created https://github.com/marimo-team/mkdocs-marimo

It is early so please provide feedback! (and recommend to use the latest marimo with it)

@patrick-kidger you can disable reactivity globally and locally, you can find the configuration options here.

[patrick-kidger]

Thanks! Unfortunately I don't think this is quite what the original issue was about: this is a way to write cells directly into markdown, not a way to take an existing .py file and host it through mkdocs.

As for reactivity, indeed, I already found the relevant part of the documentation. What I didn't see was a guarantee that doing this would result in skipping what I assume is otherwise a very large JS download.

[mscolnick]

not a way to take an existing .py file and host it through mkdocs.

@patrick-kidger - this plugin does allow that too (just not documented on the readme yet). Let me know if i am understanding the request correctly.

You can, do:

# Some document 

This will inline my notebook

!marimo_file notebook.py

Or you can reference a .py file in your nav:

nav:
  - Overview: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Notebooks in Navigation: getting-started/nav_notebook.py  # <- this is a marimo file

Both above may only exist reactively, so it will likely need some additional work for your use-case.

What I didn't see was a guarantee that doing this would result in skipping what I assume is otherwise a very large JS download.

Right now our UI elements heavily use web-components which require downloading our JS and CSS. I don't think we will avoid downloading the JS anytime soon. We do lazy-load a lot of our javascript, but we be more aggressive about this.

[patrick-kidger]

just not documented on the readme yet

Ah, that's why! I took a look through the rest of the docs too but it wasn't clear that this was possible.

Right now our UI elements heavily use web-components which require downloading our JS and CSS. I don't think we will avoid downloading the JS anytime soon.

Ah, that's a shame! I'll stick to Jupyter for the standard display some code + display it's text output for now, and give this a try when I need something more heavyweight. (As another open source maintainer, I totally understand wanting to focus on other priorities. :) )

[mscolnick]

I appreciate the help and feedback @patrick-kidger. I will let you know if we end getting the outputs more light-weight.