Merge pull request #138 from ekiefl/nb-docs-support

Notebook docs support

.github/workflows/paper.yml

@@ -13,7 +13,7 @@ jobs:
           journal: joss
           paper-path: paper.md
       - name: Upload
-        uses: actions/upload-artifact@v1
+        uses: actions/upload-artifact@v4
         with:
           name: paper
           # This is the output path where Pandoc will write the compiled

docs/.gitignore

@@ -1,2 +1,3 @@
 /_build
 /autoapi
+*.ipynb

docs/README.md

@@ -6,6 +6,8 @@ To generate a local copy of the documentation, make sure you've installed poetry
 poetry install --with docs
 ```
 
+Additionally, `pandoc` needs to be installed: https://pandoc.org/installing.html
+
 Then navigate to this directory and run:
 
 ```

docs/conf.py

@@ -28,6 +28,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "nbsphinx",
     "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
     "sphinx_copybutton",
@@ -49,13 +50,23 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 # NOTE: Don't use this for excluding python files, use `autoapi_ignore` below
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints", "**.ipynb", "**README.md"]
 
 # -- Global options ----------------------------------------------------------
 
 # Don't mess with double-dash used in CLI options
 smartquotes_action = "qe"
 
+# -- Notebook rendering -------------------------------------------------
+
+# Something to consider: https://dokk.org/documentation/nbsphinx/0.9.3/prolog-and-epilog/
+nbsphinx_epilog = """"""
+nbsphinx_prolog = """"""
+
+nbsphinx_custom_formats = {
+    ".pct.py": ["jupytext.reads", {"fmt": "py:percent"}],
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for