From 9b57485a8461ef45b98fa064d1f83018aebb9490 Mon Sep 17 00:00:00 2001
From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Date: Mon, 16 Dec 2024 21:59:51 +0100
Subject: [PATCH] Add a linter to check the images' alt text (#117)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In order to meet the [IBM Accessibility Requirements](https://www.ibm.com/able/requirements/requirements) for the API docs, we need to ensure that all images have appropriate alt text so that users can understand any meaningful visuals. The alt text should serve the same purpose as the images on the page, conveying the same meaning rather than describing visual characteristics. In addition, if an image contains important words for understanding the content, the alt text should include those words as well.

This PR adds a linter to check that all images have alt text. The current invalid images, if any, have been included in an allowlist that will help us to not break CI before the text is added.

If the script detects an image without alt text, it will show an error indicating the file where the image is located and the line where we are using a sphinx directive like `.. image::` or `.. plot::` that generates an image. Example:

```
💔 Some images are missing the alt text

Errors found in qiskit_ibm_runtime/fake_provider/__init__.py:
- Error in line 34: .. plot::

Alt text is crucial for making documentation accessible to all users. It should serve the same purpose as the images on the page, conveying the same meaning rather than describing visual characteristics. When an image contains words that are important to understanding the content, the alt text should include those words as well.
```

To fix the error, the `:alt: [Your text here]` option must be added under the lines indicated in the error messages. However, If the `.. plot::` directive is used, but no image is generated, you can use the option `:nofigs:`.
---
 tox.ini | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tox.ini b/tox.ini
index 2b2b23e..9955a26 100644
--- a/tox.ini
+++ b/tox.ini
@@ -21,6 +21,9 @@ commands =
   nbqa ruff --fix docs/
 
 [testenv:lint]
+image-tester-commit = 7ae965ccf21c39e5170334ec7f4882756883860a
+deps = 
+  git+https://github.com/Qiskit/documentation.git@{[testenv:lint]image-tester-commit}\#egg=sphinx-alt-text-validator&subdirectory=scripts/image-tester
 basepython = python3.10
 extras =
   lint
@@ -31,6 +34,7 @@ commands =
   nbqa ruff docs/
   mypy qiskit_addon_sqd/
   pylint -rn qiskit_addon_sqd/ test/
+  sphinx-alt-text-validator -f qiskit_addon_sqd
   nbqa pylint -rn docs/
   reno lint