✨ change to py:percent notebooks

- use "text" based (not json) format notebooks (py:percent)
- done through jupytext

.gitignore

@@ -20,6 +20,7 @@ _build
 _static
 _templates
 /docs/reference
+/docs/jupyter_execute
 
 # MacOS automatically creates these files
 .DS_Store

docs/conf.py

@@ -56,13 +56,19 @@
 # Rendering
 nb_merge_streams = True
 
+# https://myst-nb.readthedocs.io/en/latest/authoring/custom-formats.html#write-custom-formats
+nb_custom_formats = {
+    ".py": ["jupytext.reads", {"fmt": "py:percent"}]
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db",
+                    ".DS_Store", "jupyter_execute", "conf.py",]
 
 
 # Intersphinx options

docs/index.rst

@@ -1,27 +1,24 @@
-.. mockup documentation master file, created by
-   sphinx-quickstart on Mon Aug 28 14:09:15 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 The mockup package
-==================================
+==================
 
 Mockup is a Python package with some simple example code.
 To get started, explore the :class:`mockup.Circle` class.
 
 
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Tutorial
 
    tutorial/tutorial
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Contents:
 
-   reference/modules
+   reference/mockup
 
 .. toctree::
    :hidden:

docs/tutorial/tutorial.py

@@ -0,0 +1,21 @@
+# %% [markdown]
+# # Mockup tutorial
+
+# %%
+from mockup import mockup
+
+# %%
+mockup.add_one(-11)
+
+# %%
+list(mockup.flatten_ints([[9, 11], [12], [4, 5]]))
+
+# %%
+c2 = mockup.Circle.from_circumference(100)
+round(c2.radius, 3)
+
+# %%
+c2  # repr
+
+# %% [markdown]
+#

pyproject.toml

@@ -29,6 +29,7 @@ docs = [
   "myst-nb",
   "ipywidgets",
   "sphinx-new-tab-link!=0.2.2",
+  "jupytext",
 ]
 
 # Configure the Ruff linter: Ignore error number 501