Change to py:percent notebooks for docs (#5)

* ✨ change to py:percent notebooks

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

* ✨ add dev dependencies

Author: enryH

.github/workflows/cicd.yml

@@ -126,4 +126,4 @@ jobs:
               # remove repository key to set the default to pypi (not test.pypi.org) 
               repository-url: https://test.pypi.org/legacy/
               user: __token__
-              password: ${{ secrets.PYPI_API_TOKEN }}
+              password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

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

README.md

@@ -124,7 +124,7 @@ docs\conf.py:
 Install package so that new code is picked up in a restared python interpreter:
 
 ```
-pip install -e .
+pip install -e ".[dev]"
 ```
 
 ## TestPyPI
@@ -143,4 +143,4 @@ The documentation is build using readthedocs automatically. See
 [project on Readthedocs](https://readthedocs.org/projects/rasmussenlab-python-package/).
 
 - make sure to enable build from PRs in the settings (advanded settings)
-- checkout configuration file: [`.readthedocs.yaml`](.readthedocs.yaml)
+- checkout configuration file: [`.readthedocs.yaml`](.readthedocs.yaml)

docs/conf.py

@@ -56,13 +56,22 @@
 # 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.ipynb

@@ -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]
+#

docs/tutorial/tutorial.py

@@ -1,7 +1,7 @@
 [project]
 authors = [
-  {name = "Jakob Nybo Nissen", email = "[email protected]"},
-  {name = "Henry Webel", email = "[email protected]"},
+  { name = "Jakob Nybo Nissen", email = "[email protected]" },
+  { name = "Henry Webel", email = "[email protected]" },
 ]
 description = "A small example package"
 name = "rasmussenlab-mockup"
@@ -29,11 +29,13 @@ docs = [
   "myst-nb",
   "ipywidgets",
   "sphinx-new-tab-link!=0.2.2",
+  "jupytext",
 ]
+dev = ["black", "ruff", "pytest"]
 
 # Configure the Ruff linter: Ignore error number 501
 [tool.ruff]
-ignore = ["E501"]
+lint.ignore = ["E501"]
 
 [build-system]
 build-backend = "setuptools.build_meta"