Feature/issue 1274 notebook format check

.github/workflows/ci.yaml

@@ -102,6 +102,8 @@ jobs:
 
       shell: ${{steps.filter.outputs.shell || steps.filter.outputs.ci}}
       shell_files: ${{steps.filter.outputs.shell_files}}
+
+      notebooks: ${{steps.filter.outputs.notebooks || steps.filter.outputs.ci}}
     steps:
       - name: Check out a copy of the OpenFermion git repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -135,6 +137,8 @@ jobs:
             shell:
               - '**/*.sh'
               - 'check/*'
+            notebooks:
+              - '**/*.ipynb'
 
   python-checks:
     if: needs.changes.outputs.python == 'true'
@@ -418,13 +422,40 @@ jobs:
           # shellcheck disable=SC2086
           shellcheck ${CHANGED_FILES}
 
+  notebook-checks:
+    if: needs.changes.outputs.notebooks == 'true'
+    name: Notebook format checks
+    needs: changes
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Check out a copy of the git repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Python and restore cache
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{inputs.python_ver || env.python_ver}}
+          cache: pip
+          cache-dependency-path: ${{env.python_dep_files}}
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install requirements
+        run: pip install -r dev_tools/requirements/envs/pytest.env.txt
+
+      - name: Check notebook format
+        run: check/nbformat
+
   report-results:
     name: CI
     if: always()
     needs:
       - coverage
       - docker-lint
       - json-lint
+      - notebook-checks
       - pytest
       - pytest-compat
       - pytest-extra

check/all

@@ -99,6 +99,7 @@ fi
 run check/mypy
 run check/pytest-and-incremental-coverage "${rev[@]}"
 run check/shellcheck
+run check/nbformat
 
 # ~~~~ Summarize the results and exit with a status code ~~~~
 

check/nbformat

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -euo pipefail
+
+declare -r usage="\
+Usage: ${0##*/} [--help] [--apply]
+
+Checks Jupyter notebook (.ipynb) format using tensorflow_docs.tools.nbfmt.
+
+Without --apply, exits 0 if all notebooks are formatted and 1 otherwise.
+With --apply, reformats notebooks in place.
+"
+
+# Get the working directory to the repo root.
+thisdir=$(dirname "${BASH_SOURCE[0]:?}")
+repo_dir=$(git -C "${thisdir}" rev-parse --show-toplevel)
+cd "${repo_dir}"
+
+opt_apply=0
+for arg in "$@"; do
+    case "${arg}" in
+        -h | --help)
+            echo "${usage}"
+            exit 0
+            ;;
+        --apply)
+            opt_apply=1
+            ;;
+        *)
+            echo "Unknown argument: '${arg}'" >&2
+            echo "See '${0} --help' for usage." >&2
+            exit 1
+            ;;
+    esac
+done
+
+if ! python -c "import tensorflow_docs.tools.nbfmt"; then
+    echo "tensorflow-docs is not installed." >&2
+    exit 2
+fi
+
+declare -a notebook_paths=(
+    docs
+    src/openfermion/resource_estimates/pbc/notebooks
+)
+
+my_nbfmt() {
+    python -m tensorflow_docs.tools.nbfmt --indent=1 "$@"
+}
+
+exit_code=0
+if output=$(my_nbfmt --test "${notebook_paths[@]}" 2>&1); then
+    echo "Notebooks are formatted."
+elif (( opt_apply )); then
+    my_nbfmt "${notebook_paths[@]}" &&
+    echo "Reformatted notebooks." ||
+    exit_code=$?
+else
+    echo "The following notebooks require formatting:" >&2
+    grep '^-' <<<"${output}" >&2 || echo "${output}" >&2
+    echo "Run 'check/nbformat --apply' to fix notebooks." >&2
+    exit_code=1
+fi
+
+exit "${exit_code}"

check/shellcheck

@@ -57,6 +57,7 @@ required_shell_scripts=(
     check/all
     check/format-incremental
     check/mypy
+    check/nbformat
     check/pylint
     check/pylint-changed-files
     check/pytest

dev_tools/requirements/deps/pytest.txt

@@ -6,3 +6,4 @@ pytest-retry
 pytest-xdist
 
 nbformat
+tensorflow-docs

dev_tools/requirements/envs/dev.env.txt

@@ -1,24 +1,24 @@
 #
-# This file is autogenerated by pip-compile with Python 3.10
+# This file is autogenerated by pip-compile with Python 3.13
 # by the following command:
 #
 #    pip-compile --output-file=envs/dev.env.txt deps/format.txt deps/mypy.txt deps/pip-tools.txt deps/pylint.txt deps/pytest.txt deps/resource_estimates_runtime.txt deps/runtime.txt deps/shellcheck.txt
 #
+absl-py==2.4.0
+    # via tensorflow-docs
 ase==3.28.0
     # via -r deps/resource_estimates_runtime.txt
 ast-serialize==0.5.0
     # via mypy
+astor==0.8.1
+    # via tensorflow-docs
 astroid==3.3.11
     # via pylint
 attrs==26.1.0
     # via
     #   cirq-core
     #   jsonschema
     #   referencing
-backports-asyncio-runner==1.2.0 ; python_full_version < "3.11"
-    # via
-    #   -r deps/runtime.txt
-    #   pytest-asyncio
 black==26.5.1
     # via -r deps/format.txt
 build==1.5.0
@@ -33,6 +33,13 @@ click==8.4.1
     # via
     #   black
     #   pip-tools
+colorama==0.4.6
+    # via
+    #   build
+    #   click
+    #   pylint
+    #   pytest
+    #   tqdm
 contourpy==1.3.2
     # via
     #   -r deps/runtime.txt
@@ -47,8 +54,6 @@ dill==0.4.1
     # via pylint
 duet==0.2.9
     # via cirq-core
-exceptiongroup==1.3.1
-    # via pytest
 execnet==2.1.2
     # via pytest-xdist
 fastjsonschema==2.21.2
@@ -71,6 +76,8 @@ jaxlib==0.4.38
     # via
     #   -r deps/resource_estimates_runtime.txt
     #   jax
+jinja2==3.1.6
+    # via tensorflow-docs
 jsonschema==4.26.0
     # via nbformat
 jsonschema-specifications==2025.9.1
@@ -81,6 +88,8 @@ kiwisolver==1.5.0
     # via matplotlib
 librt==0.11.0
     # via mypy
+markupsafe==3.0.3
+    # via jinja2
 matplotlib==3.10.9
     # via
     #   ase
@@ -100,7 +109,9 @@ mypy-extensions==1.1.0
     #   black
     #   mypy
 nbformat==5.10.4
-    # via -r deps/pytest.txt
+    # via
+    #   -r deps/pytest.txt
+    #   tensorflow-docs
 networkx==3.4.2
     # via
     #   -r deps/runtime.txt
@@ -152,6 +163,8 @@ pluggy==1.6.0
     # via
     #   pytest
     #   pytest-cov
+protobuf==7.35.0
+    # via tensorflow-docs
 pubchempy==1.0.5
     # via -r deps/runtime.txt
 pygments==2.20.0
@@ -192,6 +205,8 @@ pytokens==0.4.1
     # via black
 pytz==2026.2
     # via pandas
+pyyaml==6.0.3
+    # via tensorflow-docs
 referencing==0.37.0
     # via
     #   jsonschema
@@ -220,15 +235,8 @@ sympy==1.14.0
     # via
     #   -r deps/runtime.txt
     #   cirq-core
-tomli==2.4.1
-    # via
-    #   black
-    #   build
-    #   coverage
-    #   mypy
-    #   pip-tools
-    #   pylint
-    #   pytest
+tensorflow-docs==2025.2.19.33219
+    # via -r deps/pytest.txt
 tomlkit==0.15.0
     # via pylint
 tqdm==4.67.3
@@ -247,13 +255,8 @@ types-setuptools==82.0.0.20260518
     # via -r deps/mypy.txt
 typing-extensions==4.15.0
     # via
-    #   astroid
-    #   black
     #   cirq-core
-    #   exceptiongroup
     #   mypy
-    #   pytest-asyncio
-    #   referencing
 tzdata==2026.2
     # via pandas
 urllib3==2.7.0