[Docs] automate docs with eslint-doc-generator

ljharb · Oct 27, 2022 · 6d7a857 · 6d7a857
1 parent 0bdf95b
commit 6d7a857
Show file tree

Hide file tree

Showing 49 changed files with 322 additions and 241 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -28,20 +28,6 @@
         "eslint-plugin/require-meta-type": "off",
       },
     },
-    {
-      "files": ["markdown.config.js"],
-      "parserOptions": {
-        "sourceType": "script",
-      },
-      "rules": {
-        "no-console": 0,
-        "import/no-extraneous-dependencies":  [
-           "error",
-           { "devDependencies": true },
-        ],
-        "strict": ["error", "global"],
-      },
-    },
     {
       "files": ["__tests__/src/rules/*.js"],
       "extends": ["plugin:eslint-plugin/tests-recommended"],

diff --git a/README.md b/README.md
diff --git a/docs/rules/accessible-emoji.md b/docs/rules/accessible-emoji.md
@@ -1,4 +1,8 @@
-# [Deprecated] accessible-emoji
+# jsx-a11y/accessible-emoji
+
+❌ This rule is deprecated.
+
+<!-- end auto-generated rule header -->
 
 Emoji have become a common way of communicating content to the end user. To a person using a screenreader, however, they may not be aware that this content is there at all. By wrapping the emoji in a `<span>`, giving it the `role="img"`, and providing a useful description in `aria-label`, the screenreader will treat the emoji as an image in the accessibility tree with an accessible name for the end user.
 

diff --git a/docs/rules/alt-text.md b/docs/rules/alt-text.md
@@ -1,9 +1,15 @@
-# alt-text
+# jsx-a11y/alt-text
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Enforce that all elements that require alternative text have meaningful information to relay back to the end user. This is a critical component of accessibility for screen reader users in order for them to understand the content's purpose on the page. By default, this rule checks for alternative text on the following elements: `<img>`, `<area>`, `<input type="image">`, and `<object>`.
 
 ## How to resolve
+
 ### `<img>`
+
 An `<img>` must have the `alt` prop set with meaningful text or as an empty string to indicate that it is an image for decoration.
 
 For images that are being used as icons for a button or control, the `alt` prop should be set to an empty string (`alt=""`).
@@ -12,20 +18,25 @@ For images that are being used as icons for a button or control, the `alt` prop
 <button>
   <img src="icon.png" alt="" />
   Save
+
 </button>
 ```
+
 The content of an `alt` attribute is used to calculate the accessible label of an element, whereas the text content is used to produce a label for the element. For this reason, adding a label to an icon can produce a confusing or duplicated label on a control that already has appropriate text content.
 
 ### `<object>`
+
 Add alternative text to all embedded `<object>` elements using either inner text, setting the `title` prop, or using the `aria-label` or `aria-labelledby` props.
 
 ### `<input type="image">`
+
 All `<input type="image">` elements must have a non-empty `alt` prop set with a meaningful description of the image or have the `aria-label` or `aria-labelledby` props set.
 
 ### `<area>`
+
 All clickable `<area>` elements within an image map have an `alt`, `aria-label` or `aria-labelledby` prop that describes the purpose of the link.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 
@@ -66,19 +77,22 @@ return (
   <header>
     <Image alt="Logo" src="logo.jpg" />
   </header>
+
 );
 ```
 
 Note that passing props as spread attribute without explicitly the necessary accessibility props defined will cause this rule to fail. Explicitly pass down the set of props needed for rule to pass. Use `Image` component above as a reference for destructuring and applying the prop. **It is a good thing to explicitly pass props that you expect to be passed for self-documentation.** For example:
 
 #### Bad
+
 ```jsx
 function Foo(props) {
   return <img {...props} />
 }
 ```
 
 #### Good
+
 ```jsx
 function Foo({ alt, ...props}) {
     return <img alt={alt} {...props} />
@@ -89,6 +103,7 @@ function Foo({ alt, ...props}) {
 function Foo(props) {
     const {
         alt,
+
         ...otherProps
     } = props;
 
@@ -97,6 +112,7 @@ function Foo(props) {
 ```
 
 ### Succeed
+
 ```jsx
 <img src="foo" alt="Foo eating a sandwich." />
 <img src="foo" alt={"Foo eating a sandwich."} />
@@ -111,6 +127,7 @@ function Foo(props) {
 
 <area aria-label="foo" />
 <area aria-labelledby="id1" />
+
 <area alt="This is descriptive!" />
 
 <input type="image" alt="This is descriptive!" />
@@ -120,26 +137,31 @@ function Foo(props) {
 ```
 
 ### Fail
+
 ```jsx
 <img src="foo" />
 <img {...props} />
 <img {...props} alt /> // Has no value
 <img {...props} alt={undefined} /> // Has no value
 <img {...props} alt={`${undefined}`} /> // Has no value
 <img src="foo" role="presentation" /> // Avoid ARIA if it can be achieved without
+
 <img src="foo" role="none" /> // Avoid ARIA if it can be achieved without
 
 <object {...props} />
 
+
 <area {...props} />
 
 <input type="image" {...props} />
 ```
 
 ## Accessibility guidelines
+
 - [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
 
 ### Resources
+
 - [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
 - [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
 - [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)

diff --git a/docs/rules/anchor-ambiguous-text.md b/docs/rules/anchor-ambiguous-text.md
@@ -1,8 +1,12 @@
-# anchor-ambiguous-text
+# jsx-a11y/anchor-ambiguous-text
+
+☑️ This rule is _disabled_ in the `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 Enforces `<a>` values are not exact matches for the phrases "click here", "here", "link", "a link", or "learn more". Screenreaders announce tags as links/interactive, but rely on values for context. Ambiguous anchor descriptions do not provide sufficient context for users.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument with the parameter `words`.
 
@@ -33,13 +37,15 @@ Note that this rule still disallows ambiguous `aria-label` or `alt` values.
 Note that this rule is case-insensitive, trims whitespace, and ignores certain punctuation (`[,.?¿!‽¡;:]`). It only looks for **exact matches**.
 
 ### Succeed
+
 ```jsx
 <a>read this tutorial</a> // passes since it is not one of the disallowed words
 <a>${here}</a> // this is valid since 'here' is a variable name
 <a aria-label="tutorial on using eslint-plugin-jsx-a11y">click here</a> // the aria-label supersedes the inner text
 ```
 
 ### Fail
+
 ```jsx
 <a>here</a>
 <a>HERE</a>

diff --git a/docs/rules/anchor-has-content.md b/docs/rules/anchor-has-content.md
@@ -1,8 +1,12 @@
-# anchor-has-content
+# jsx-a11y/anchor-has-content
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Enforce that anchors have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 

diff --git a/docs/rules/anchor-is-valid.md b/docs/rules/anchor-is-valid.md
@@ -1,4 +1,8 @@
-# anchor-is-valid
+# jsx-a11y/anchor-is-valid
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 The HTML `<a>` element, with a valid `href` attribute, is formally defined as representing a **hyperlink**. That is, a link between one HTML document and another, or between one location inside an HTML document and another location inside the same document.
 
@@ -159,7 +163,7 @@ This button element can now also be used inline in text.
 
 Once again we stress that this is an inferior implementation and some users will encounter difficulty to use your website, however, it will allow a larger group of people to interact with your website than the alternative of ignoring the rule's warning.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 

diff --git a/docs/rules/aria-activedescendant-has-tabindex.md b/docs/rules/aria-activedescendant-has-tabindex.md
@@ -1,4 +1,8 @@
-# aria-activedescendant-has-tabindex
+# jsx-a11y/aria-activedescendant-has-tabindex
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 `aria-activedescendant` is used to manage focus within a [composite widget](https://www.w3.org/TR/wai-aria/#composite).
 The element with the attribute `aria-activedescendant` retains the active document

diff --git a/docs/rules/aria-props.md b/docs/rules/aria-props.md
@@ -1,4 +1,8 @@
-# aria-props
+# jsx-a11y/aria-props
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Elements cannot use an invalid ARIA attribute. This will fail if it finds an `aria-*` property that is not listed in [WAI-ARIA States and Properties spec](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties).
 

diff --git a/docs/rules/aria-proptypes.md b/docs/rules/aria-proptypes.md
@@ -1,4 +1,8 @@
-# aria-proptypes
+# jsx-a11y/aria-proptypes
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 ARIA state and property values must be valid.
 

diff --git a/docs/rules/aria-role.md b/docs/rules/aria-role.md
@@ -1,8 +1,12 @@
-# aria-role
+# jsx-a11y/aria-role
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Elements with ARIA roles must use a valid, non-abstract ARIA role. A reference to role definitions can be found at [WAI-ARIA](https://www.w3.org/TR/wai-aria/#role_definitions) site.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 

diff --git a/docs/rules/aria-unsupported-elements.md b/docs/rules/aria-unsupported-elements.md
@@ -1,4 +1,8 @@
-# aria-unsupported-elements
+# jsx-a11y/aria-unsupported-elements
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Certain reserved DOM elements do not support ARIA roles, states and properties. This is often because they are not visible, for example `meta`, `html`, `script`, `style`. This rule enforces that these DOM elements do not contain the `role` and/or `aria-*` props.
 

diff --git a/docs/rules/autocomplete-valid.md b/docs/rules/autocomplete-valid.md
@@ -1,8 +1,12 @@
-# autocomplete-valid
+# jsx-a11y/autocomplete-valid
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Ensure the autocomplete attribute is correct and suitable for the form field it is used with.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 
@@ -22,7 +26,7 @@ This rule takes one optional object argument of type object:
 <input type="text" autocomplete="name" />
 
 <!-- Good: MyInput is not listed in inputComponents -->
-<MyInput autocomplete="incorrect" /> 
+<MyInput autocomplete="incorrect" />
 ```
 
 ### Fail
@@ -34,7 +38,7 @@ This rule takes one optional object argument of type object:
 <input type="email" autocomplete="url" />
 
 <!-- Bad: MyInput is listed in inputComponents -->
-<MyInput autocomplete="incorrect" /> 
+<MyInput autocomplete="incorrect" />
 ```
 
 ## Accessibility guidelines

diff --git a/docs/rules/click-events-have-key-events.md b/docs/rules/click-events-have-key-events.md
@@ -1,4 +1,8 @@
-# click-events-have-key-events
+# jsx-a11y/click-events-have-key-events
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Enforce `onClick` is accompanied by at least one of the following: `onKeyUp`, `onKeyDown`, `onKeyPress`. Coding for the keyboard is important for users with physical disabilities who cannot use a mouse, AT compatibility, and screenreader users. This does not apply for interactive or hidden elements.
 

diff --git a/docs/rules/control-has-associated-label.md b/docs/rules/control-has-associated-label.md
@@ -1,4 +1,8 @@
-# control-has-associated-label
+# jsx-a11y/control-has-associated-label
+
+💼 This rule is _disabled_ in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Enforce that a control (an interactive element) has a text label.
 
@@ -50,7 +54,7 @@ You can configure the rule to be aware of your custom components. Refer to the R
 <CustomInput label="Surname" type="text" value={value} />
 ```
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 

diff --git a/docs/rules/heading-has-content.md b/docs/rules/heading-has-content.md
@@ -1,8 +1,12 @@
-# heading-has-content
+# jsx-a11y/heading-has-content
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Enforce that heading elements (`h1`, `h2`, etc.) have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object:
 

diff --git a/docs/rules/html-has-lang.md b/docs/rules/html-has-lang.md
@@ -1,4 +1,8 @@
-# html-has-lang
+# jsx-a11y/html-has-lang
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 <html> elements must have the lang prop. This rule is largely superseded by the [`lang` rule](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/lang.md).
 

diff --git a/docs/rules/iframe-has-title.md b/docs/rules/iframe-has-title.md
@@ -1,4 +1,8 @@
-# iframe-has-title
+# jsx-a11y/iframe-has-title
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 `<iframe>` elements must have a unique title property to indicate its content to the user.
 

diff --git a/docs/rules/img-redundant-alt.md b/docs/rules/img-redundant-alt.md
@@ -1,8 +1,12 @@
-# img-redundant-alt
+# jsx-a11y/img-redundant-alt
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 Enforce img alt attribute does not contain the word image, picture, or photo. Screenreaders already announce `img` elements as an image. There is no need to use words such as *image*, *photo*, and/or *picture*.
 
-## Rule details
+## Rule options
 
 This rule takes one optional object argument of type object: