Merge pull request #6 from jdranczewski/dev

v0.11.0

docs/requirements.txt

@@ -5,3 +5,5 @@ pyqtgraph==0.13.3
 numpy==1.26.2
 sphinx==7.2.5
 sphinx-rtd-theme==1.3.0rc1
+nbsphinx==0.9.5
+ipykernel==6.29.5

docs/source/conf.py

@@ -19,7 +19,9 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon"]
+extensions = [
+    "sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon",
+    "nbsphinx", "sphinx.ext.autosectionlabel"]
 
 templates_path = ["_templates"]
 exclude_patterns = []

docs/source/index.rst

@@ -150,6 +150,8 @@ you may want to update ``ipykernel`` if your cells are not running after an exce
 Next steps
 ==========
 
+The :ref:`Tutorial` is a great place to start - have a look or run it yourself to learn interactively!
+
 Some more detailed examples are located on GitHub: `how to construct an app <https://github.com/jdranczewski/puzzlepiece/tree/main/examples>`_
 or `how to code a Piece <https://github.com/jdranczewski/puzzlepiece/blob/main/puzzlepiece/pieces/random_number.py>`_. Examples of more complex
 Pieces `are also available <https://github.com/jdranczewski/puzzlepiece/tree/main/puzzlepiece/pieces>`_.
@@ -162,6 +164,7 @@ This documentation is meant as a good way to familiarise yourself with the libra
    :caption: Contents:
 
    modules
+   tutorial
 
 
 Indices and tables

docs/source/puzzlepiece.extras.ipython_shims.rst

@@ -0,0 +1,41 @@
+puzzlepiece.extras.ipython_shims module
+=======================================
+
+Import this module to get access to useful puzzlepiece-related Magics::
+
+   from puzzlepiece.extras import ipython_shims
+
+%%pzp_script
+------------
+
+Magic for running the cell as puzzlepiece script::
+
+   %%pzp_script
+   set:piece_name:param_name:25
+   prompt:Param changed
+
+Assumes the :class:`~puzzlepiece.puzzle.Puzzle` is in the global namespace
+as ``puzzle``. A different name can be provided as an argument to the magic: 
+``%%pzp_script puzzle_variable``.
+
+See :func:`puzzlepiece.parse.run` for the full scripting syntax.
+
+%%safe_run
+------------
+
+Magic for running the cell with a safety function in case of a crash::
+
+   # Cell 1
+   def close_shutter():
+      puzzle["shutter"]["open"].set_value(0)
+
+   # Cell 2
+   %%safe_run close_shutter
+   raise Exception
+
+Running cell 2 will raise an exception, but the magic catches the exception,
+closes the shutter, and then the original exception is re-raised. Another
+useful usecase is sending a Slack message when a crash occurs.
+
+This is similar in spirit to :func:`puzzlepiece.puzzle.Puzzle.custom_excepthook`,
+but works in Notebooks in constrast to that.

docs/source/puzzlepiece.extras.rst

@@ -2,8 +2,9 @@ puzzlepiece.extras module
 =========================
 
 The extras module contains additional features that are useful, but not part of the
-core puzzlepiece functionality. Currently this is just the ``datagrid`` - a Widget that
-can be added to your Pieces, with multiple Piece-like Rows that use params for data storage
+core puzzlepiece functionality. Currently these are ``ipython_shims`` (a small collection
+of Notebook magics) and the ``datagrid`` - a Widget that can be added to your Pieces,
+with multiple Piece-like Rows that use params for data storage
 and manipulation.
 
 The extras modules have to be imported explicitly::
@@ -17,4 +18,5 @@ The extras modules have to be imported explicitly::
 .. toctree::
    :maxdepth: 2
 
+   puzzlepiece.extras.ipython_shims
    puzzlepiece.extras.datagrid