Docs/notebook plotly

.github/workflows/docs.yml

@@ -10,6 +10,7 @@ on:
     branches: [main]
     paths:
       - "docs/**"
+      - "examples/**"          # the example notebooks are rendered into the site
       - "mkdocs.yml"
       - "src/**"
       - ".github/workflows/docs.yml"

.gitignore

@@ -34,3 +34,5 @@ scratch/
 
 # MkDocs build output
 site/
+# mkdocs-jupyter render cache
+.cache/

.pre-commit-config.yaml

@@ -16,4 +16,7 @@ repos:
 - repo: https://github.com/kynan/nbstripout
   rev: 0.8.1
   hooks:
-    - id: nbstripout
+    - id: nbstripout
+      # The example notebooks are rendered into the docs site from their stored
+      # outputs (mkdocs-jupyter, execute: false), so keep their outputs intact.
+      exclude: '^(examples|docs/examples)/.*\.ipynb$'

docs/examples/bundle_adjustment.ipynb

@@ -0,0 +1 @@
+../../examples/bundle_adjustment.ipynb

docs/examples/pipeline_walkthrough.ipynb

@@ -0,0 +1 @@
+../../examples/pipeline_walkthrough.ipynb

docs/guides/library.md

@@ -128,5 +128,10 @@ with io.VideoWriter("out.mp4", fps=30) as writer:
 
 ## Examples
 
-- [`examples/bundle_adjustment.ipynb`](https://github.com/NeLy-EPFL/deeperfly/blob/main/examples/bundle_adjustment.ipynb) — the bundle-adjustment walkthrough.
-- [`examples/pipeline_walkthrough.ipynb`](https://github.com/NeLy-EPFL/deeperfly/blob/main/examples/pipeline_walkthrough.ipynb) — the pipeline one stage at a time.
+Two runnable notebooks, rendered here with their outputs (the Plotly figures
+stay interactive):
+
+- [Bundle adjustment](../examples/bundle_adjustment.ipynb) — build a multi-camera
+  rig, perturb it, and recover it with `bundle_adjust`.
+- [Pipeline walkthrough](../examples/pipeline_walkthrough.ipynb) — the full
+  2D→3D pipeline one stage at a time.

mkdocs.yml

@@ -39,6 +39,9 @@ nav:
       - CLI usage: guides/cli.md
       - Writing configs: guides/configuration.md
       - Library API: guides/library.md
+  - Examples:
+      - Bundle adjustment: examples/bundle_adjustment.ipynb
+      - Pipeline walkthrough: examples/pipeline_walkthrough.ipynb
   - How it works:
       - Pipeline stages: explanation/pipeline.md
       - Keypoint locations: explanation/keypoints.md
@@ -81,6 +84,14 @@ extra_javascript:
 
 plugins:
   - search
+  # Render the example notebooks (symlinked into docs/examples/) straight into
+  # the site. execute: false -> use the outputs already stored in the .ipynb, so
+  # the build stays fast and needs no torch/jax/data; the Plotly figures stay
+  # interactive.
+  - mkdocs-jupyter:
+      execute: false
+      include_source: true
+      ignore_h1_titles: false
   - mkdocstrings:
       handlers:
         python:

pyproject.toml

@@ -72,7 +72,12 @@ build-backend = "uv_build"
 [dependency-groups]
 dev = [
     "ipykernel>=7.2.0",
-    "matplotlib>=3.10",   # ad-hoc plotting in the example notebooks (not used by the package)
+    # Notebook plotting only (examples/*.ipynb; not used by the package). Plotly
+    # draws the interactive figures, which stay interactive when the notebooks are
+    # rendered into the docs; matplotlib still draws a few static panels in
+    # pipeline_walkthrough.ipynb.
+    "matplotlib>=3.10",
+    "plotly>=6.8.0",
 ]
 test = [
     "pytest>=9.0.3",
@@ -86,6 +91,10 @@ docs = [
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.27",
     "ruff>=0.6",   # mkdocstrings uses it to format the rendered API signatures
+    # Renders the example notebooks (examples/*.ipynb) into the site from their
+    # stored outputs (execute: false), so the Plotly figures stay interactive
+    # without importing torch/jax at build time.
+    "mkdocs-jupyter>=0.25",
 ]
 
 [tool.pytest.ini_options]