Feature/issue 1274 notebook format check

[rosspeili]

Closes #1274

Adds check/nbformat to validate tracked .ipynb files with tensorflow_docs.tools.nbfmt (repo root, Cirq-style), wired into check/all, shellcheck, and CI. Adds tensorflow-docs to the pytest and dev lockfiles.

Notebook formatting is in #1322 and should merge before this PR.

[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

[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. 🙏

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[rosspeili]

@mhucka thanks again for the patience and tips.

Rebased onto current main and fixed check/nbformat, I had the wrong module (nbformat vs nbfmt, per Cirq). Ran nbfmt locally on py3.13 and formatted the notebooks and lockfiles regenerated on top of main.

Let me know if I am missing anything. <3

[mhucka]

Thanks for the quick work. This is better! There's just a small niggle in check/nbformat; please check the comment there.

I didn't anticipate that the notebooks would actually not conform to the format and would produce a lot of diffs. It is better to split out the formatting differences to a separate PR because then the PR commit can be adde to .git-blame-ignore-revs so that git blame output is less noisy. So, could we please proceed as follows?

1. Pull out the tutorial file changes that result from running check/nbformat --apply and move them to a separate PR.
2. I will review & merge that separate PR first.
3. Then we will merge this PR (#1274).
4. Then I will do a new PR to add the commit of PR #1 to .git-blame-ignore-revs.

[mhucka]

One more minor thing. In the PR description, it's better to omit this statement:

Earlier version used the wrong module (nbformat) which was fixed to nbfmt with --apply for local fixes.

When this PR is merged, the changes will be squashed in the git history and it will not be easy for readers to figure out what this comment refers to. The description only needs to refer to the PR as it stands and not the history of the PR.

(I think you may have intended the comment to be helpful information for reviewers of the updated PR. That's kind, and I understand the impulse, but nevertheless, it turns out it's actually counter-productive in the long run. I used to do the same thing, and had to unlearn this particular habit …)

[rosspeili]

Understood and respected. ✅️

[rosspeili]

@mhucka split as requested with notebook formatting now in #1322, while this PR is only the check script, CI wiring, and lockfiles (7 files). Also applied your feedback on . for nbfmt and notebook_files in the paths filter.

Thanks so much for the feedback and patience <3