Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a Jupyter notebook page. #157

Merged
merged 8 commits into from
Oct 24, 2023
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/links.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
40 changes: 40 additions & 0 deletions docs/pages/jupyter-notebooks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
title: Jupyter Notebooks
layout: default
---

# Jupyter notebooks

We generally recommend developing code for packaging into python modules if possible.
However occasionally we support researchers who prefer a notebook environment or projects which want to provide examples and tutorials in notebook format.
samcunliffe marked this conversation as resolved.
Show resolved Hide resolved

## 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

<-->