Feature/issue 1274 notebook format check

[rosspeili]

Closes #1274

What was solved based on the 1274 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 https://github.com/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, --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.

Rational behind changes

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

[gemini-code-assist]

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.

[rosspeili]

Hey @mhucka any feedback on this also? No stress, just checking in. Thanks.

[mhucka]

@rosspeili Thank you for the contribution, and sorry for the long delay in getting back to this.

The merge conflicts are because files in the repo changed in the meantime, which is my fault for not reviewing this sooner, so I will take the time to fix it in a moment and push an updated version to your branch. (I hope you don't mind – it will save everyone time.)

A bigger problem is that this does not work. How did you test this? This is what happens when I run check/nbformat:

./check/nbformat
Found 15 notebook(s).
Running notebook format checker...
  Checking: docs/fqe/guide/introduction.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/diagonal_coulomb_evolution.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/fermi_hubbard.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/fqe_vs_openfermion_quadratic_hamiltonians.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/fqe/tutorials/hamiltonian_time_evolution_and_expectation_estimation.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/binary_code_transforms.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/bosonic_operators.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/circuits_1_basis_change.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/circuits_2_diagonal_coulomb_trotter.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/circuits_3_arbitrary_basis_trotter.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/intro_to_openfermion.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/intro_workshop_exercises.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: docs/tutorials/jordan_wigner_and_bravyi_kitaev_transforms.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: src/openfermion/resource_estimates/pbc/notebooks/isdf.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat
  Checking: src/openfermion/resource_estimates/pbc/notebooks/resource_estimates.ipynb
~/.pyenv/versions/o12/bin/python: No module named tensorflow_docs.tools.nbformat

[mhucka]

tensorflow_docs.tools does not have an nbformat.

This could not have worked. How was this tested, exactly?

[rosspeili]

Hey @mhucka no stress at all. Appreciate the review and comments as always. As disclosed also in previews PRs, the PR description indeed is formatted with AI, based on a dump, but will make it more concise or just drop the original blurp. Code is hand written and passed through AI for review before pr. I used existing tests with py 3.13, but will check again and come back to you asap.

Please do feel free to push to my branch if available. Or suggest and I'll approve. 🙏