-
Notifications
You must be signed in to change notification settings - Fork 86
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Image checker for images' alt text and HTML tags (#2349)
This pull request adds an image checker to ensure all images have an alt text defined, which is crucial for accessibility, and that we don't have any `<img>` HTML tag. The output of the check shows the file name that contains invalid images and the images' names. Ex: ``` Error in file 'docs/guides/custom-transpiler-pass.ipynb': - The image '/images/guides/custom-transpiler-pass/DAG.png' does not have alt text. Invalid images found 💔 See https://github.com/Qiskit/documentation#images for instructions. ``` The PR builds on the work done by @shraddha-aangiras on #1800. I have made some changes to simplify the code and incorporated @Eric-Arellano's feedback. Thank you both for the work you've done! Closes #1651 --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Co-authored-by: Shraddha Aangiras <63237790+shraddha-aangiras@users.noreply.github.com>
- Loading branch information
3 people
authored
Nov 21, 2024
1 parent
3eadfe1
commit 7a59fa9
Showing
7 changed files
with
156 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| // This code is a Qiskit project. | ||
| // | ||
| // (C) Copyright IBM 2024. | ||
| // | ||
| // This code is licensed under the Apache License, Version 2.0. You may | ||
| // obtain a copy of this license in the LICENSE file in the root directory | ||
| // of this source tree or at http://www.apache.org/licenses/LICENSE-2.0. | ||
| // | ||
| // Any modifications or derivative works of this code must retain this | ||
| // copyright notice, and modified files need to carry a notice indicating | ||
| // that they have been altered from the originals. | ||
|
|
||
| import { globby } from "globby"; | ||
| import { collectInvalidImageErrors } from "../lib/markdownImages.js"; | ||
| import { readMarkdown } from "../lib/markdownReader.js"; | ||
|
|
||
| async function main() { | ||
| const files = await globby(["docs/**/*.{ipynb,mdx}", "!docs/api/**/*.mdx"]); | ||
| const fileErrors: string[] = []; | ||
|
|
||
| for (const file of files) { | ||
| const markdown = await readMarkdown(file); | ||
| const imageErrors = await collectInvalidImageErrors(markdown); | ||
|
|
||
| if (imageErrors.size) { | ||
| fileErrors.push( | ||
| `Error in file '${file}':\n\t- ${[...imageErrors].join("\n\t- ")}`, | ||
| ); | ||
| } | ||
| } | ||
|
|
||
| if (fileErrors.length) { | ||
| fileErrors.forEach((error) => console.log(error)); | ||
| console.error( | ||
| "\n💔 Some images have problems. See https://github.com/Qiskit/documentation#images for instructions.\n", | ||
| ); | ||
| process.exit(1); | ||
| } | ||
| console.log("✅ All images are valid.\n"); | ||
| } | ||
|
|
||
| main().then(() => process.exit()); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| // This code is a Qiskit project. | ||
| // | ||
| // (C) Copyright IBM 2023. | ||
| // | ||
| // This code is licensed under the Apache License, Version 2.0. You may | ||
| // obtain a copy of this license in the LICENSE file in the root directory | ||
| // of this source tree or at http://www.apache.org/licenses/LICENSE-2.0. | ||
| // | ||
| // Any modifications or derivative works of this code must retain this | ||
| // copyright notice, and modified files need to carry a notice indicating | ||
| // that they have been altered from the originals. | ||
|
|
||
| import { expect, test } from "@playwright/test"; | ||
|
|
||
| import { collectInvalidImageErrors } from "./markdownImages.js"; | ||
|
|
||
| test("Test the finding of invalid images", async () => { | ||
| const markdown = ` | ||
| # A header | ||
|  | ||
|  | ||
|  | ||
|  | ||
|  | ||
| <img src="/images/HTMLexample1.jpg" alt="" width="200"/> | ||
| <img src="/images/HTMLexample2.jpg" alt="Example" width="200"/> | ||
|  | ||
| `; | ||
| const images = await collectInvalidImageErrors(markdown); | ||
| const correct_images = new Set([ | ||
| "The image '/images/HTMLexample1.jpg' uses an HTML <img> tag instead of markdown syntax.", | ||
| "The image '/images/HTMLexample2.jpg' uses an HTML <img> tag instead of markdown syntax.", | ||
| "The image '/images/invalid_img1.png' does not have alt text.", | ||
| "The image '/images/invalid_img2.png' does not have alt text.", | ||
| ]); | ||
|
|
||
| expect(images).toEqual(correct_images); | ||
| }); |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| // This code is a Qiskit project. | ||
| // | ||
| // (C) Copyright IBM 2024. | ||
| // | ||
| // This code is licensed under the Apache License, Version 2.0. You may | ||
| // obtain a copy of this license in the LICENSE file in the root directory | ||
| // of this source tree or at http://www.apache.org/licenses/LICENSE-2.0. | ||
| // | ||
| // Any modifications or derivative works of this code must retain this | ||
| // copyright notice, and modified files need to carry a notice indicating | ||
| // that they have been altered from the originals. | ||
|
|
||
| import { load } from "cheerio"; | ||
| import { unified } from "unified"; | ||
| import { Root } from "remark-mdx"; | ||
| import { visit } from "unist-util-visit"; | ||
| import remarkParse from "remark-parse"; | ||
| import remarkGfm from "remark-gfm"; | ||
| import remarkStringify from "remark-stringify"; | ||
|
|
||
| export async function collectInvalidImageErrors( | ||
| markdown: string, | ||
| ): Promise<Set<string>> { | ||
| const imagesErrors = new Set<string>(); | ||
|
|
||
| await unified() | ||
| .use(remarkParse) | ||
| .use(remarkGfm) | ||
| .use(() => (tree: Root) => { | ||
| visit(tree, "image", (node) => { | ||
| if (!node.alt) { | ||
| imagesErrors.add(`The image '${node.url}' does not have alt text.`); | ||
| } | ||
| }); | ||
| visit(tree, "html", (node) => { | ||
| const $ = load(node.value); | ||
| if ($("img").length) { | ||
| imagesErrors.add( | ||
| `The image '${$("img").attr("src")}' uses an HTML <img> tag instead of markdown syntax.`, | ||
| ); | ||
| } | ||
| }); | ||
| }) | ||
| .use(remarkStringify) | ||
| .process(markdown); | ||
|
|
||
| return imagesErrors; | ||
| } |