Add a Jupyter notebook page. (#157)

Putting my best linters found so far. Does not completely solve #49.

Anyone with experience linting jupyter notebooks is very welcome to
review.

---------

Co-authored-by: Matt Graham <[email protected]>

.github/workflows/links.yml

@@ -22,10 +22,11 @@ jobs:
         uses: lycheeverse/[email protected]
         with:
           # Exclude the image.sc forum (which works) but returns 403 from
-          # github runners, ignore the project slug README since the links are
+          # github runners and exclude relative links to other pages. Ignore
+          # the whole of the project slug README since the links are
           # necessarily not real links - i.e. demos and to be filled by
           # cookiecutter values.
-          args: "--verbose --exclude https://forum.image.sc/ --exclude-path '{{cookiecutter.project_slug}}/README.md'  -- ."
+          args: "--verbose --exclude https://forum.image.sc/ --exclude docs/pages --exclude-path '{{cookiecutter.project_slug}}/README.md'  -- ."
           fail: true
           jobSummary: true
         env:

docs/pages/jupyter-notebooks.md

@@ -0,0 +1,41 @@
+---
+title: Jupyter Notebooks
+layout: default
+---
+
+# Jupyter notebooks
+
+We generally recommend packaging resuable code components into Python modules where possible.
+However occasionally we support researchers who prefer a notebook environment or projects which want to provide examples and tutorials in notebook format.
+Notebooks can also be a valid alternative to Python scripts for running and recording the results of numerical experiments for example.
+
+## Linting
+
+Many of [our recommended linters](linting) don't work out-of-the box on Jupyter notebooks, however [nbQA] has been found to work well.
+This is a translation tool that can be used to run our recommended linters over notebooks.
+
+There is one exception: we've found that [black]'s own Jupyter extension works more reliably than [black] via [nbQA].
+
+| Name             | Short description                                                                | 🚦  |
+| ---------------- | -------------------------------------------------------------------------------- | :-: |
+| `black[jupyter]` | (also `black-jupyter`) [black] with the optional Jupyter extension.              | 🟢  |
+| [nbQA]           | Recommended for all other linters ([ruff], [isort]) and [mypy].                  | 🟢  |
+| [pre-commit]     | Has cell output cleanup hooks (if desired). Also found to work well with [nbQA]. | 🟢  |
+| `nbqa black`     | [black] via [nbQA].                                                              | 🟠  |
+
+<!-- URLs for a more readable table & prose 👆 -->
+
+[black]: https://nbqa.readthedocs.io/en/latest/index.html
+[nbQA]: https://nbqa.readthedocs.io/en/latest/index.html
+[isort]: https://pycqa.github.io/isort
+[ruff]: https://github.com/charliermarsh/ruff
+[mypy]: https://mypy.readthedocs.io/en/stable
+[pre-commit]: https://github.com/kynan/nbstripout
+
+<!-- TODO: more sections to consider>
+
+## IDE plugins
+
+## CI
+
+<-->