Add alt text to API docs

[arnaucasau]

Issue

The API docs don't have alt text for their images, and we need to add it by modifying the Python files in the 9 APIs repos. Each repo has a linter that can be used to verify how many images fail to provide an alternative text.

Each repo's linter has an allowlist defined at the beginning of the script with a list of all the current files that contain an image without alt text. The linter can be found at tools/verify_image.py.

Instructions

1. Go to the tools/verify_image.py script in each of the 9 APIs.
2. Look at the ALLOWLIST_MISSING_ALT_TEXT list to find all the files with images without alt text.
3. Remove the file you want to fix from the ALLOWLIST_MISSING_ALT_TEXT list.
4. Open a terminal and go to the top-level folder of the repo.
5. Run the script by executing python tools/verify_image.py to get all the images without alt text in the file.

Example of the output:

💔 Some images are missing the alt text

Errors found in qiskit_ibm_runtime/fake_provider/example.py:
- Error in line 34: .. plot::
- Error in line 55: .. image::
- Error in line 63: .. 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.

This means that the file qiskit_ibm_runtime/fake_provider/example.py has images defined in lines 34, 55, and 63 without alt text.

6. Find the code lines in the file and add the option :alt: [your alt text] under the directive .. image:: or .. plot:: found in each line. The .. plot:: directive is sometimes used to run code that doesn't generate an image. In those cases the option :nofigs: should be added instead of :alt: [your alt text].
7. Remove the filename from the ALLOWLIST_MISSING_ALT_TEXT list if all the images are fixed.

List of the API repos to check (with the new instructions, all APIs can be checked):

• qiskit
• qiskit-ibm-runtime
• qiskit-ibm-transpiler
• qiskit-addon-aqc-tensor
• qiskit-addon-obp
• qiskit-addon-mpf
• qiskit-addon-sqd
• qiskit-addon-cutting
• qiskit-addon-utils

[arnaucasau]

New Instructions! The linter is now installable using pip install and can be used in all the repos 🎉

1. Open a terminal and install the alt text checker by running:

pip install git+https://github.com/Qiskit/documentation.git#subdirectory=scripts/image-tester

2. Go to the top-level folder of the repo.
3. Run the script by executing the following command:

sphinx-alt-text-validator -f [FolderToCheck]

where [FolderToCheck] is the folder name where our python files are located. Ex. qiskit_ibm_runtime for runtime or qiskit_addon_utils for qiskit-addon-utils

4. Find the files and lines containing invalid images in the output of the previous command.

Example of the output:

💔 Some images are missing the alt text

Errors found in qiskit_ibm_runtime/fake_provider/example.py:
- Error in line 34: .. plot::
- Error in line 55: .. image::
- Error in line 63: .. 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.

This means that the file qiskit_ibm_runtime/fake_provider/example.py has images defined in lines 34, 55, and 63 without alt text.

5. Add the option :alt: [your alt text] under the directive .. image:: or .. plot:: found in each line. The .. plot:: directive is sometimes used to run code that doesn't generate an image. In those cases the option :nofigs: should be added instead of :alt: [your alt text].

[beckykd]

Images in Qiskit missing alt text: qiskit-missing-alt-text.txt

[beckykd]

Images in Qiskit Runtime missing alt text:

• Errors found in qiskit-ibm-runtime\qiskit_ibm_runtime\fake_provider_init_.py:

• Error in line 34: .. plot::

• Error in line 55: .. plot::

• Error in line 63: .. plot::

• Errors found in qiskit-ibm-runtime\qiskit_ibm_runtime\transpiler\passes\scheduling\dynamical_decoupling.py:

• Error in line 56: .. plot::

• Error in line 88: .. plot::

• Errors found in qiskit-ibm-runtime\qiskit_ibm_runtime\transpiler\passes\scheduling_init_.py:

• Error in line 51: .. plot::

• Error in line 102: .. plot::

• Error in line 137: .. plot::

• Error in line 152: .. plot::

• Error in line 176: .. plot::

• Error in line 207: .. plot::

• Error in line 226: .. plot::

• Error in line 240: .. plot::

• Error in line 256: .. plot::

• Error in line 274: .. plot::

• Error in line 294: .. plot::

• Error in line 313: .. plot::

• Error in line 328: .. plot::

• Error in line 342: .. plot::

• Error in line 363: .. plot::

• Error in line 382: .. plot::

• Error in line 406: .. plot::

[beckykd]

Qiskit Runtime updates: Qiskit/qiskit-ibm-runtime#2079

[beckykd]

Qiskit updates: Qiskit/qiskit#13555

[beckykd]

PR for OBP addon: Qiskit/qiskit-addon-obp#45

[beckykd]

PR for Cutting addon Qiskit/qiskit-addon-cutting#725

[beckykd]

PR for Utils addon: Qiskit/qiskit-addon-utils#64

[beckykd]

PR for MPF addon: Qiskit/qiskit-addon-mpf#43

[beckykd]

All repos are done; just waiting for approvals / merges.