Add tests to sphinx-alt-text-validator (#2502)

This PR creates tests for the `sphinx-alt-text-validator` and recovers
the tests of the `nb-tester` in CI. See
#2445 (review)
and
#2425 (comment)

Example of the test running:
https://github.com/Qiskit/documentation/actions/runs/12390997779/job/34587197281?pr=2502#step:22:1

.github/workflows/main.yml

@@ -86,3 +86,6 @@ jobs:
               "To fix, install tox and run `tox -e fix`."
             )
             sys.exit(1)
+
+      - name: Test packages
+        run: tox -e tests

scripts/image-tester/sphinx_alt_text_validator/__init__.py

@@ -11,7 +11,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
-from .verify_images import validate_image
+from .verify_images import validate_file
 import multiprocessing
 import glob
 import sys
@@ -24,12 +24,12 @@ def main() -> None:
     parser.add_argument("-s", "--skip", nargs="+")
     args = parser.parse_args()
 
-    skip_list = args.skip or []
+    skip_list = set(args.skip or [])
     files = glob.glob(f"{args.folder}/**/*.py", recursive=True)
     filtered_files = [file for file in files if file not in skip_list]
 
     with multiprocessing.Pool() as pool:
-        results = pool.map(validate_image, filtered_files)
+        results = pool.map(validate_file, filtered_files)
 
     failed_files = {
         file: image_errors for file, image_errors in results if image_errors

scripts/image-tester/sphinx_alt_text_validator/verify_images.py

@@ -18,7 +18,7 @@
 
 def is_image(line: str) -> bool:
     """Determine if a line is an image"""
-    return line.strip().startswith((".. image:", ".. plot:"))
+    return line.strip().startswith((".. image::", ".. plot::"))
 
 
 def is_option(line: str) -> bool:
@@ -36,12 +36,12 @@ def is_valid_image(options: list[str]) -> bool:
     return alt_exists or nofigs_exists
 
 
-def validate_image(file_path: str) -> tuple[str, list[str]]:
-    """Validate all the images of a single file"""
+def validate_images(file_content: str) -> list[str]:
+    """Validate all the images found on a given reStructured Text"""
 
     invalid_images: list[str] = []
 
-    lines = Path(file_path).read_text(encoding="utf-8").splitlines()
+    lines = file_content.splitlines()
 
     image_found = False
     options: list[str] = []
@@ -65,4 +65,11 @@ def validate_image(file_path: str) -> tuple[str, list[str]]:
         image_found = is_image(line)
         options = []
 
+    return invalid_images
+
+
+def validate_file(file_path: str) -> tuple[str, list[str]]:
+    """Validate all the images of a single file"""
+    file_content = Path(file_path).read_text(encoding="utf-8")
+    invalid_images = validate_images(file_content)
     return (file_path, invalid_images)

scripts/image-tester/test/test_validate_image.py

@@ -0,0 +1,45 @@
+from sphinx_alt_text_validator.verify_images import ( validate_images )
+
+EXAMPLE_RST_WITH_IMAGES = """\
+.. image::  /example_image/example1.png
+    :width: 400
+
+.. image::  /example_image/example2.png
+    :alt: Example
+
+.. image::  /example_image/example3.png
+
+.. plot::
+    :include-source:
+    from numpy import sqrt
+    from qiskit.quantum_info import Statevector
+    sv=Statevector([1/sqrt(2), 0, 0, -1/sqrt(2)])
+    sv.draw(output='hinton')
+
+.. plot::
+    :alt: Example
+    :include-source:
+    from numpy import sqrt
+    from qiskit.quantum_info import Statevector
+    sv=Statevector([1/sqrt(2), 0, 0, -1/sqrt(2)])
+    sv.draw(output='hinton')
+
+.. image::  /example_image/example4.png
+
+.. plot::
+    :include-source:
+    :nofigs:
+    from numpy import sqrt
+    from qiskit.quantum_info import Statevector
+    sv=Statevector([1/sqrt(2), 0, 0, -1/sqrt(2)])
+"""
+
+
+def test_validate_image():
+    invalid_images = validate_images(EXAMPLE_RST_WITH_IMAGES)
+    assert invalid_images == [
+        '- Error in line 1: .. image::  /example_image/example1.png',
+        '- Error in line 7: .. image::  /example_image/example3.png',
+        '- Error in line 9: .. plot::',
+        '- Error in line 24: .. image::  /example_image/example4.png',
+    ]

tox.ini

@@ -23,8 +23,9 @@ commands =
     fix: ruff format {posargs:docs}
     fix: ruff check --fix {posargs:docs}
 
-[testenv:nb-tester]
+[testenv:tests]
 deps =
   -e scripts/nb-tester
+  -e scripts/image-tester
   pytest
-commands = pytest scripts/nb-tester
+commands = pytest