docs: module autoreloading (#3420)

marimo-team · Jan 14, 2025 · 352c5f2 · 352c5f2
1 parent 18a70bb
commit 352c5f2
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 21 deletions.
diff --git a/docs/guides/coming_from/jupyter.md b/docs/guides/coming_from/jupyter.md
@@ -164,24 +164,25 @@ subprocess.run(["ls", "-l"])
 
 ### Common magic commands replacements
 
-| Magic Command | Replacement |
-|--------------|-------------|
-| %cd | `os.chdir()`, see also [`mo.notebook_dir()`][marimo.notebook_dir] |
-| %clear | Right-click or toggle the cell actions |
-| %debug | Python's built-in debugger: `breakpoint()` |
-| %env | `os.environ` |
-| %load | N/A - use Python imports |
-| %load_ext | N/A |
-| %matplotlib | marimo auto-displays plots |
-| %pwd | `os.getcwd()` |
-| %who_ls | `dir()`, `globals()`, [`mo.refs()`][marimo.refs], [`mo.defs()`][marimo.defs] |
-| %system | `subprocess.run()` |
-| %%time | `time.perf_counter()` or Python's timeit module |
-| %%timeit | Python's timeit module |
-| %%writefile | `with open("file.txt", "w") as f: f.write()` |
-| %%capture | [`mo.capture_stdout()`][marimo.capture_stdout], [`mo.capture_stderr()`][marimo.capture_stderr] |
-| %%html | [`mo.Html()`][marimo.Html] or [`mo.md()`][marimo.md] |
-| %%latex | [`mo.md(r'$$...$$')`][marimo.md] |
+| Magic Command | Replacement                                                                                    |
+| ------------- | ---------------------------------------------------------------------------------------------- |
+| %cd           | `os.chdir()`, see also [`mo.notebook_dir()`][marimo.notebook_dir]                              |
+| %clear        | Right-click or toggle the cell actions                                                         |
+| %debug        | Python's built-in debugger: `breakpoint()`                                                     |
+| %env          | `os.environ`                                                                                   |
+| %load         | N/A - use Python imports                                                                       |
+| %load_ext     | N/A                                                                                            |
+| %autoreload   | marimo's [module autoreloader](../../editor_features/module_autoreloading/)                       |
+| %matplotlib   | marimo auto-displays plots                                                                     |
+| %pwd          | `os.getcwd()`                                                                                  |
+| %who_ls       | `dir()`, `globals()`, [`mo.refs()`][marimo.refs], [`mo.defs()`][marimo.defs]                   |
+| %system       | `subprocess.run()`                                                                             |
+| %%time        | `time.perf_counter()` or Python's timeit module                                                |
+| %%timeit      | Python's timeit module                                                                         |
+| %%writefile   | `with open("file.txt", "w") as f: f.write()`                                                   |
+| %%capture     | [`mo.capture_stdout()`][marimo.capture_stdout], [`mo.capture_stderr()`][marimo.capture_stderr] |
+| %%html        | [`mo.Html()`][marimo.Html] or [`mo.md()`][marimo.md]                                           |
+| %%latex       | [`mo.md(r'$$...$$')`][marimo.md]                                                               |
 
 ### Installing packages with marimo's package manager
 

diff --git a/docs/guides/editor_features/module_autoreloading.md b/docs/guides/editor_features/module_autoreloading.md
@@ -0,0 +1,34 @@
+# Module autoreloading
+
+marimo has an advanced module autoreloader built-in, which you can
+enable in the [notebook settings](../../configuration/runtime_configuration/).
+When you make edits to Python modules that your notebook has imported, the
+module autoreloader will automatically mark cells that use them as stale and,
+optionally, automatically run them.
+
+!!! question "Why autoreload?"
+
+    Autoreloading enables a workflow that many developers find
+    productive: develop complex logic in Python modules, and use the marimo
+    notebook as a DAG or main script that orchestrates your logic.
+
+Based on static analysis, the reloader only runs cells affected by your edits.
+The reloader is recursive, meaning that marimo tracks modifications for modules
+imported by your notebook's imported modules too. These two featuers make
+marimo's module autoreloader far more advanced than IPython's.
+
+Autoreloading comes in two types:
+
+1. **autorun**: automatically re-runs cells affected by module modification.
+
+<figure>
+<video controls loop width="100%" height="100%" align="center" src="/_static/docs-module-reloading.mp4"> </video>
+<figcaption align="center">When set to autorun, marimo's reloader automatically run cells when you edit Python files.</figcaption>
+</figure>
+
+2. **lazy**: marks cells affected by module modifications as stale, letting you know which cells need to be re-run.
+
+<figure>
+<video controls loop width="100%" height="100%" align="center" src="/_static/docs-module-reloading-lazy.mp4"> </video>
+<figcaption align="center">When set to lazy, marimo's reloader marks cells as stale when you edit Python files.</figcaption>
+</figure>
diff --git a/docs/guides/editor_features/package_management.md b/docs/guides/editor_features/package_management.md
@@ -15,4 +15,4 @@ they use. This makes it possible to share standalone notebooks without shipping
 `requirements.txt` files alongside them, and guarantees your notebooks will
 work weeks, months, even years into the future.
 
-To learn more, see the [Package Reproducibility Guide](../package_reproducibility.md)
+To learn more, see the [Package Reproducibility Guide](../package_reproducibility.md).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -90,9 +90,10 @@ nav:
       - Editor features:
           - Editor features: guides/editor_features/index.md
           - Editor overview: guides/editor_features/overview.md
-          - AI Completion: guides/editor_features/ai_completion.md
+          - AI completion: guides/editor_features/ai_completion.md
+          - Package management: guides/editor_features/package_management.md
+          - Module autoreloading: guides/editor_features/module_autoreloading.md
           - Hotkeys: guides/editor_features/hotkeys.md
-          - Package Management: guides/editor_features/package_management.md
       - Run notebooks as apps: guides/apps.md
       - Run notebooks as scripts: guides/scripts.md
       - Test notebooks: