Improve file filtering in CI (Qiskit#734)

The `transpiler-stages` notebook is broken, but will be tested in CI any
time someone edits it (even if just changing copy etc.). This breaks PRs
that are perfectly fine.

This PR ignores excluded files completely. I also took the opportunity
to:
- improve the code readability somewhat (i.e. less `path for path in
paths if path`),
- print a message when notebooks are skipped, otherwise someone running
`tox` locally might believe their notebook was fine even though it never
ran.

---------

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>

scripts/nb-tester/test-notebook.py

@@ -17,6 +17,7 @@
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
+from typing import Iterator
 
 import nbclient
 import nbconvert
@@ -35,6 +36,34 @@
 ]
 
 
+def filter_paths(paths: list[Path], submit_jobs: bool) -> Iterator[Path]:
+    """
+    Filter out any paths we don't want to run, printing messages.
+    """
+    for path in paths:
+        if path.suffix != ".ipynb":
+            print(f"ℹ️ Skipping {path}; file is not `.ipynb` format.")
+            continue
+
+        if any(path.match(glob) for glob in NOTEBOOKS_EXCLUDE):
+            this_file = Path(__file__).resolve()
+            print(
+                f"ℹ️ Skipping {path}; to run it, edit `NOTEBOOKS_EXCLUDE` in {this_file}."
+            )
+            continue
+
+        if (
+            not submit_jobs
+            and any(path.match(glob) for glob in NOTEBOOKS_THAT_SUBMIT_JOBS)
+        ):
+            print(
+                f"ℹ️ Skipping {path} as it submits jobs; use the --submit-jobs flag to run it."
+            )
+            continue
+
+        yield path
+
+
 @dataclass(frozen=True)
 class ExecuteOptions:
     write: bool
@@ -214,15 +243,12 @@ def create_argument_parser() -> argparse.ArgumentParser:
     args = create_argument_parser().parse_args()
 
     paths = map(Path, args.filenames or find_notebooks(submit_jobs=args.submit_jobs))
-    if not args.submit_jobs:
-        paths = [path for path in paths if not any(path.match(glob) for glob in NOTEBOOKS_THAT_SUBMIT_JOBS)]
+    filtered_paths = filter_paths(paths, submit_jobs=args.submit_jobs)
 
     # Execute notebooks
     start_time = datetime.now()
     print("Executing notebooks:")
-    results = [
-        execute_notebook(path, args) for path in paths if path.suffix == ".ipynb"
-    ]
+    results = [execute_notebook(path, args) for path in filtered_paths]
     print("Checking for trailing jobs...")
     results.append(cancel_trailing_jobs(start_time))
     if not all(results):