Skip to content

Feature/issue 1274 notebook format check#1299

Open
rosspeili wants to merge 5 commits into
quantumlib:mainfrom
rosspeili:feature/issue-1274-notebook-format-check
Open

Feature/issue 1274 notebook format check#1299
rosspeili wants to merge 5 commits into
quantumlib:mainfrom
rosspeili:feature/issue-1274-notebook-format-check

Conversation

@rosspeili
Copy link
Copy Markdown

Closes #1274

What was solved based on the issue

OpenFermion has 8 Jupyter notebook tutorials in docs/tutorials/, but none of the scripts in
check/ ever looked at them. This PR adds a new check/nbformat script that validates all
tracked .ipynb files using the TensorFlow Docs notebook
format checker, and wires it into the rest of the CI pipeline.

Changes

  • check/nbformat (new file) which is a bash script that finds all .ipynb files tracked by git and
    runs python -m tensorflow_docs.tools.nbformat on each one. Defaults to check-only mode, pass
    --fix to reformat notebooks in place, or --help for usage info. Follows the same structure
    and conventions as the other scripts in check/.

  • check/all, added run check/nbformat so it runs as part of master check.

  • check/shellcheck, also added check/nbformat to the required scripts list (in sorted order)
    so shellcheck verifies itself the new script is sound.

  • dev_tools/requirements/deps/pytest.txt, added tensorflow-docs alongside the existing
    nbformat dep (explaining decision below).

  • dev_tools/requirements/envs/pytest.env.txt / dev.env.txt, regenerated pinned lockfiles
    to include tensorflow-docs==2025.2.19.33219 and its transitive deps (protobuf, pyyaml).

  • .github/workflows/ci.yaml, added a notebook-checks CI job that triggers when .ipynb
    files change and runs check/nbformat. Also added to report-results so it's required.

Why this way

1. Check-only vs. auto-fix?

The script supports both. By default it's read-only and exits non-zero if any notebook fails,
which is what we want in CI. The --fix flag is there for devs who want to fix their
notebooks locally without manually figuring out what's wrong. This matches the pattern found in
check/format-incremental (which also has an --apply flag).

2. Should check/nbformat run unconditionally in check/all?

I think yes. Unlike Python linting or formatting, notebook format issues aren't tied to which files changed
in a given commit, but they're property of the repo as a whole. So it runs unconditionally alongside
check/mypy and check/shellcheck, rather than only in the changed files branch.

3. Where to put the tensorflow-docs dependency?

tensorflow-docs already had its own orphaned deps/tensorflow-docs.txt file that wasn't
referenced by any compiled environment. Rather than creating yet another new file, I added it
to deps/pytest.txt, which contained nbformat already (the package for reading notebooks). Both
are notebook-related checking tools used outside of normal test runs, so I thought they belong together.
This keeps the number of dep files as low as possible and the grouping easy to grasp.

Let me know how this looks, or if there's something I missed. <3

rosspeili added 3 commits May 6, 2026 12:26
Add check/nbformat, a new bash script that checks the format of all
tracked Jupyter notebook (.ipynb) files using the TensorFlow Docs
notebook format checker (tensorflow_docs.tools.nbformat).

The script:
- Discovers all .ipynb files tracked by git via git ls-files
- Runs python -m tensorflow_docs.tools.nbformat on each notebook
- Defaults to check-only mode (non-destructive)
- Accepts --fix to reformat notebooks in place
- Accepts --help to print usage information
- Exits non-zero if any notebook fails the format check

Wire check/nbformat into:
- check/all: called unconditionally alongside check/mypy and
  check/shellcheck, since notebook format is structural and not
  related to which Python files changed
- check/shellcheck: added to the required_shell_scripts list
  (in sorted order) so shellcheck verifies the new script is present

Add tensorflow-docs to dev_tools/requirements/deps/pytest.txt
alongside the existing nbformat dep, since both are needed for
notebook-related checks and belong in the same env grouping.

Add a notebook-checks CI job to .github/workflows/ci.yaml that
triggers when .ipynb files change and runs check/nbformat using
the pytest.env.txt environment (which includes tensorflow-docs).
Also add the new job to report-results so it is a required check.
Run pip-compile to update pytest.env.txt and dev.env.txt with the
pinned version of tensorflow-docs (==2025.2.19.33219), which was
added to deps/pytest.txt for use by check/nbformat. Also picks up
its transitive deps protobuf and pyyaml.
…tion

Regenerated pytest.env.txt and dev.env.txt with pip-compile after
accepting upstream version bumps during merge conflict resolution.
tensorflow-docs==2025.2.19.33219 is now correctly pinned alongside
the updated package versions from main.
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new script, check/nbformat, to validate and fix Jupyter notebook formatting using tensorflow_docs.tools.nbformat, and updates the project's dependency requirements and lockfiles. The review highlights two critical issues: the inefficiency of invoking the format checker in a loop rather than passing all files at once, and the breaking of environment compatibility for older Python versions caused by regenerating lockfiles with Python 3.13 instead of the project's minimum supported version.

Comment thread check/nbformat
Comment thread dev_tools/requirements/envs/dev.env.txt Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Check scripts do not check tutorials, but should

1 participant