Notebooks as Documentation¶

I wasn't necessarily going to discuss notebooks, in part because I'm like many of you and wish to improve my noteboks, but I do want to show how easy they are to publish (which at least solves ONE person dependency).

Also, I'm oging to start talking about notebooks by telling you to use marimo (their docs are made with mkdocs!), despite being new to it personally. Marimo has many awesome features, but here are the core wins for me:

1. it's pure python, so diffs are WAY easier to read (check out jupytext to write notebooks in markdown)
2. things update one the fly, so you can't get different results by running cells in different order (and other opinionated things that help with this)

You can also easily publish marimo notebooks with mkdocs-marimo.

Anyways...

Publishing notebooks in deployed docs is usually as easy as adding an extension. For example in mkdocs you can use mkdocs-jupyter. You will need to add to mkdocs.yml:

plugins:
  - mkdocs-jupyter

Run the notebooks?¶

mkdocs-jupyter is not running this file when the docs are built, so notice how code blocks have their run execution order

However, if you want to execute the notebooks when building the docs, you can add to the mkdocs.yml:

plugins:
  mkdocs-jupyter:
    execute_notebooks: true  # will run the notebooks
    allow_errors: false  # fail build if notebook fails, can be useful as a "test"

And now some code¶

In [3]:

import seaborn.objects as so
from seaborn import load_dataset

penguins = load_dataset("penguins")

(
    so.Plot(
        penguins, x="bill_length_mm", y="bill_depth_mm",
        color="species", pointsize="body_mass_g",
    )
    .add(so.Dot())
)

import seaborn.objects as so from seaborn import load_dataset penguins = load_dataset("penguins") ( so.Plot( penguins, x="bill_length_mm", y="bill_depth_mm", color="species", pointsize="body_mass_g", ) .add(so.Dot()) )

Out[3]:

In [ ]: