New check for image alt text

[beckykd]

All images need to have alt="some alt text" , like in the following example

[shraddha-aangiras]

Hi @Eric-Arellano, is this issue similar to this one where simply alt text is to be added, or is a new check to be implemented? If a check is to be created, could you give me an outline on where it should be done? Would love to work on this issue either way :)

[Eric-Arellano]

Thanks for offering, @shraddha-aangiras! That would be an enormous help. Alt text is crucial for accessibility.

This issue is about adding a generic check, whereas https://github.com/Qiskit/documentation/issues/1659 is fixing all the current violations we have. This issue is an infra task, whereas 1659 is a content task that the technical writers can help with.

Here are some thoughts on how you could add this check:

1. Add a new files scripts/commands/checkAltText.ts, scripts/lib/extractAltText.ts, and scripts/lib/extractAltText.ts
   • For now, they should only have the copyright notice with the year set to 2024
2. Update package.json, .github/workflows/main.yml, and README.md to define and use a new command check:alt-text. Look at check:metadata for an example. Make sure that check runs the new command.
3. Implement extractAltText.ts and extractAltText.test.ts by defining a new async function extractAltText(markdown: string): Promise<AltText>. AltText can be an interface that has something like {imageName: string; altText: string | null}.
   • Note that the function intentionally takes a string as the arg rather than a file path. That makes it easier to test.
   • Your test should have some valid examples with alt text and some without
   • See this example. I think yours will look the same but you only have the image visit, and you need to get the alt text https://github.com/Qiskit/documentation/blob/ab112fe5914bcd68c7440c0bb1d0d8b3d99781e2/scripts/lib/links/extractLinks.ts#L58-L89
4. Implement checkAltText.ts
   • It should run on all files in guides/ and api/migration-guides. (Not the rest of api/). You can use globby for this
   • It should call readMarkdown() from https://github.com/Qiskit/documentation/pull/1666/files and extractAltText from the prior step. Do this for every source file
   • It should have an allowlist mechanism
   • See the other files in scripts/commands for inspiration, like checkMetadata.ts

How does this sound @shraddha-aangiras? Would you like me to assign you?

[shraddha-aangiras]

Thank you so very much for the comprehensive breakdown @Eric-Arellano! It helped me understand how to implement this and also how the checks like these work. I would love to work on this, please assign this to me! Thanks again!

[Eric-Arellano]

Great! Let me know if you have questions, and also feel free to open a draft PR with [wip] in the PR title if you want feedback on your progress.

[shraddha-aangiras]

@Eric-Arellano Thank you so much!