From 492875622b39cb2cf04bbb9248b6ed0c52ced2df Mon Sep 17 00:00:00 2001 From: Derick Montague Date: Tue, 16 Mar 2021 19:52:33 -0500 Subject: Update text wrapping in documentation To meet best practices and standards for markdown, this commit updates all markdown files used for the VuePress documentation so that each line is limited to 80 characters. Signed-off-by: Derick Montague Change-Id: I0cadb33343ce1bc331dfefd096d8137a04c33604 --- docs/guide/coding-standards/accessibility.md | 50 ++++++++--- docs/guide/coding-standards/readme.md | 18 ++-- docs/guide/components/alerts/index.md | 8 +- docs/guide/components/buttons/index.md | 12 ++- docs/guide/components/file-upload/readme.md | 15 ++-- docs/guide/components/info-tooltip/index.md | 7 +- docs/guide/components/page-section/index.md | 7 +- docs/guide/components/page-title/index.md | 11 ++- docs/guide/components/readme.md | 8 +- docs/guide/components/status-icon/readme.md | 3 +- docs/guide/components/table/index.md | 128 ++++++++++++++++++++------- docs/guide/components/toasts/index.md | 24 +++-- docs/guide/guidelines/colors.md | 27 ++++-- docs/guide/guidelines/motion.md | 21 ++++- docs/guide/quickstart/page-anatomy.md | 16 ++-- docs/guide/quickstart/store-anatomy.md | 21 +++-- docs/guide/readme.md | 24 +++-- docs/guide/unit-testing/readme.md | 105 ++++++++++++++++------ 18 files changed, 376 insertions(+), 129 deletions(-) (limited to 'docs/guide') diff --git a/docs/guide/coding-standards/accessibility.md b/docs/guide/coding-standards/accessibility.md index d53bf08d..0a9a1a75 100644 --- a/docs/guide/coding-standards/accessibility.md +++ b/docs/guide/coding-standards/accessibility.md @@ -1,9 +1,19 @@ # Accessibility Conventions and Standards -It is important that the OpenBMC Web UI meet accessibility guidelines established by the [World Wide Web Consortium (W3C)](https://www.w3.org/). These guidelines are known as the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). Making the Web UI accessible to as many users as possible is the right thing to do. In many countries, it is also legally required. Organizations providing interfaces that users with permanent or temporary disabilities can not use, may lose sales or be susceptible to discriminatory lawsuits. +It is important that the OpenBMC Web UI meet accessibility guidelines +established by the [World Wide Web Consortium (W3C)](https://www.w3.org/). These +guidelines are known as the [Web Content Accessibility Guidelines +(WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/). Making the Web UI +accessible to as many users as possible is the right thing to do. In many +countries, it is also legally required. Organizations providing interfaces that +users with permanent or temporary disabilities can not use, may lose sales or be +susceptible to discriminatory lawsuits. ## Accessibility Principles -These [principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/) reference a set of international standards from the [W3C Web Accessibility Intitiative (WAI)](https://www.w3.org/WAI/). +These +[principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/) +reference a set of international standards from the [W3C Web Accessibility +Intitiative (WAI)](https://www.w3.org/WAI/). - [Perceiveable](https://www.w3.org/WAI/fundamentals/accessibility-principles/#perceivable) - [Operable](https://www.w3.org/WAI/fundamentals/accessibility-principles/#operable) @@ -11,33 +21,53 @@ These [principles](https://www.w3.org/WAI/fundamentals/accessibility-principles/ - [Robust](https://www.w3.org/WAI/fundamentals/accessibility-principles/#robust) ## Semantic HTML -Coding the UI using semantic markup is the most important step in creating an inclusive interface. The use of [WAI-ARIA](https://www.w3.org/WAI/standards-guidelines/aria/) can help make an interface accessible to assistive technologies. However, there are two critical rules to follow: +Coding the UI using semantic markup is the most important step in creating an +inclusive interface. The use of +[WAI-ARIA](https://www.w3.org/WAI/standards-guidelines/aria/) can help make an +interface accessible to assistive technologies. However, there are two critical +rules to follow: 1. Always favor semantic markup over ARIA 2. No ARIA is better than Bad ARIA ## Testing -Assuring the Web UI meets accessibility guidelines requires a combination of automated and manual testing. Automated tests will test the application against common problems such as color contrast and ARIA use. Automated testing can be built into the CI process, integrated with code editors, and run using browser extensions. +Assuring the Web UI meets accessibility guidelines requires a combination of +automated and manual testing. Automated tests will test the application against +common problems such as color contrast and ARIA use. Automated testing can be +built into the CI process, integrated with code editors, and run using browser +extensions. -The OpenBMC Web UI developers should test their development pages using one of the tools listed in the tools section below. If using Chrome, the Lighthouse application comes bundled with the browser and also includes testing for performance and best practices. If there is an issue that is created when using a Bootstrap-Vue component, we can [create an issue in the Bootstrap-vue repo](https://github.com/bootstrap-vue/bootstrap-vue/issues/new/choose). Contributing to the Bootstrap-Vue open-source library, when possible, is strongly encouraged. +The OpenBMC Web UI developers should test their development pages using one of +the tools listed in the tools section below. If using Chrome, the Lighthouse +application comes bundled with the browser and also includes testing for +performance and best practices. If there is an issue that is created when using +a Bootstrap-Vue component, we can [create an issue in the Bootstrap-vue +repo](https://github.com/bootstrap-vue/bootstrap-vue/issues/new/choose). +Contributing to the Bootstrap-Vue open-source library, when possible, is +strongly encouraged. ## Tools - [Deque Axe](https://www.deque.com/axe/) -- [Firefox Accessibility Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) +- [Firefox Accessibility + Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) - [IBM Accessibility Tools](https://www.ibm.com/able/toolkit/tools) - [Lighthouse](https://developers.google.com/web/tools/lighthouse) ## Screen Readers - [Jaws - (Windows only)](https://webaim.org/articles/jaws/) -- [Narrator - (Windows only)](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) +- [Narrator - (Windows + only)](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) - [NVDA (Windows only)](https://webaim.org/articles/nvda/) - [Voiceover (Mac only)](https://webaim.org/articles/voiceover/) ## Resources -- [Mozilla Developer Network - Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) -- [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) +- [Mozilla Developer Network - + Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) +- [Web Content Accessibility Guidelines + (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) - [WAI-ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/) -- [WAI-ARIA Basics](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics) +- [WAI-ARIA + Basics](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics) - [WebAIM Articles](https://webaim.org/articles/) - [A11Y Project](https://a11yproject.com/) - [IBM Accessibility](https://www.ibm.com/able/) diff --git a/docs/guide/coding-standards/readme.md b/docs/guide/coding-standards/readme.md index b183256d..a6ab3669 100644 --- a/docs/guide/coding-standards/readme.md +++ b/docs/guide/coding-standards/readme.md @@ -1,11 +1,13 @@ # JavaScript and SASS -This project uses the following libraries to determine the best practices and guidelines for both SCSS and JavaScript syntax. +This project uses the following libraries to determine the best practices and +guidelines for both SCSS and JavaScript syntax. - [ESLint](https://eslint.org/) - [Prettier](https://prettier.io/) - [ESLint Plugin for Vue](https://eslint.vuejs.org/) The guidelines we are following are: -- [Vue Recommended](https://eslint.vuejs.org/rules/#priority-c-recommended-minimizing-arbitrary-choices-and-cognitive-overhead-for-vue-js-3-x) +- [Vue + Recommended](https://eslint.vuejs.org/rules/#priority-c-recommended-minimizing-arbitrary-choices-and-cognitive-overhead-for-vue-js-3-x) - [ESLint Recommended](https://eslint.org/docs/rules/) - [Prettier](https://prettier.io/docs/en/options.html) @@ -15,9 +17,15 @@ The rules are applied in the following order: 1. Prettier ## Overrides -Any overrides to a rule are located in the ESLint configuration file, `.eslintrc.js`, located in the root directory. +Any overrides to a rule are located in the ESLint configuration file, +`.eslintrc.js`, located in the root directory. ## Running the lint test -To test all files for linting, run `npm run lint`. This command will evaluate the syntax of all files and update any code that that does not require manual review. +To test all files for linting, run `npm run lint`. This command will evaluate +the syntax of all files and update any code that that does not require manual +review. -The linting script runs when code is committed, during pre-commit, and when the CI tool runs after a push to Gerrit. There is a shell script named `format-code.sh` that installs node package dependencies and runs the test script in your CI. \ No newline at end of file +The linting script runs when code is committed, during pre-commit, and when the +CI tool runs after a push to Gerrit. There is a shell script named +`format-code.sh` that installs node package dependencies and runs the test +script in your CI. \ No newline at end of file diff --git a/docs/guide/components/alerts/index.md b/docs/guide/components/alerts/index.md index 9273f8e2..aa2c5e13 100644 --- a/docs/guide/components/alerts/index.md +++ b/docs/guide/components/alerts/index.md @@ -1,7 +1,11 @@ # Alerts -An alert is an inline message that contains a short description that a user cannot manually dismiss. With exception to the error message on the login page, alerts are not triggered by user action. Success and error notifications based on user actions are created using a toast component. +An alert is an inline message that contains a short description that a user +cannot manually dismiss. With exception to the error message on the login page, +alerts are not triggered by user action. Success and error notifications based +on user actions are created using a toast component. -[Learn more about Bootstrap-vue alert options](https://bootstrap-vue.js.org/docs/components/alert) +[Learn more about Bootstrap-vue alert +options](https://bootstrap-vue.js.org/docs/components/alert) ![Alert examples](./alert.png) diff --git a/docs/guide/components/buttons/index.md b/docs/guide/components/buttons/index.md index da569a15..83b8e8a7 100644 --- a/docs/guide/components/buttons/index.md +++ b/docs/guide/components/buttons/index.md @@ -1,11 +1,17 @@ # Buttons -Buttons are used to perform an action. The main buttons in the application are the `primary` and `secondary` buttons. Buttons, like all Boostrap-vue components can be themed by setting the `variant` prop on the component to one of the [theme-color map keys](/guide/guidelines/colors). To create a button that looks like a link, set the variant value to `link`. +Buttons are used to perform an action. The main buttons in the application are +the `primary` and `secondary` buttons. Buttons, like all Boostrap-vue components +can be themed by setting the `variant` prop on the component to one of the +[theme-color map keys](/guide/guidelines/colors). To create a button that looks +like a link, set the variant value to `link`. -[Learn more about Bootstrap-vue buttons](https://bootstrap-vue.js.org/docs/components/button) +[Learn more about Bootstrap-vue +buttons](https://bootstrap-vue.js.org/docs/components/button) ### Icon only buttons -Add `btn-icon-only` class to the button and add `title` attribute to get helper text on hover over the button. +Add `btn-icon-only` class to the button and add `title` attribute to get helper +text on hover over the button. ### Enabled buttons diff --git a/docs/guide/components/file-upload/readme.md b/docs/guide/components/file-upload/readme.md index 49945308..fb833648 100644 --- a/docs/guide/components/file-upload/readme.md +++ b/docs/guide/components/file-upload/readme.md @@ -1,19 +1,24 @@ # FormFile -`FormFile` is a custom component wrapper around the Bootstrap-vue Form File component. The purpose of this component is to upload files to the BMC. +`FormFile` is a custom component wrapper around the Bootstrap-vue Form File +component. The purpose of this component is to upload files to the BMC. To use this component: 1. Import it into the single file component (SFC) 2. Add the `` tag 3. Add the optional `id` , `disabled`, `accept` and `state` prop as required -[Learn more about the Bootstrap-vue Form File component](https://bootstrap-vue.org/docs/components/form-file) +[Learn more about the Bootstrap-vue Form File +component](https://bootstrap-vue.org/docs/components/form-file) ### Optional properties -- `id`- Used to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed -- `disabled` - When set to `true`, disables the component's functionality and places it in a disabled state +- `id`- Used to set the `id` attribute on the rendered content, and used as the + base to generate any additional element IDs as needed +- `disabled` - When set to `true`, disables the component's functionality and + places it in a disabled state - `accept` - Set value to specify which file types to allow -- `state` - Controls the validation state appearance of the component. `true` for valid, `false` for invalid, or `null` for no validation state +- `state` - Controls the validation state appearance of the component. `true` + for valid, `false` for invalid, or `null` for no validation state ## Example of form file diff --git a/docs/guide/components/info-tooltip/index.md b/docs/guide/components/info-tooltip/index.md index 25425475..b6117924 100644 --- a/docs/guide/components/info-tooltip/index.md +++ b/docs/guide/components/info-tooltip/index.md @@ -1,8 +1,11 @@ # InfoTooltip -The `InfoTooltip` is a custom component that uses a Bootstrap-vue tooltip with an info icon. This custom component requires a title property containing the tooltip text to display to the user. +The `InfoTooltip` is a custom component that uses a Bootstrap-vue tooltip with +an info icon. This custom component requires a title property containing the +tooltip text to display to the user. -[Read more about the Bootstrap-vue tooltip component](https://bootstrap-vue.org/docs/components/tooltip) +[Read more about the Bootstrap-vue tooltip +component](https://bootstrap-vue.org/docs/components/tooltip) ## Example diff --git a/docs/guide/components/page-section/index.md b/docs/guide/components/page-section/index.md index ccf654e1..2a8a22ef 100644 --- a/docs/guide/components/page-section/index.md +++ b/docs/guide/components/page-section/index.md @@ -1,10 +1,13 @@ # Page section -The `` component will render semantic HTML. By adding a `:section-title` prop to the `` component, the localized text string will be rendered in an `h2` header element. +The `` component will render semantic HTML. By adding a +`:section-title` prop to the `` component, the localized text +string will be rendered in an `h2` header element. ``` vue // Example: `src/views/AccessControl/Ldap/Ldap.vue` ``` -[View the page section component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageSection.vue). \ No newline at end of file +[View the page section component source +code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageSection.vue). \ No newline at end of file diff --git a/docs/guide/components/page-title/index.md b/docs/guide/components/page-title/index.md index b51ab640..db43f29f 100644 --- a/docs/guide/components/page-title/index.md +++ b/docs/guide/components/page-title/index.md @@ -1,5 +1,7 @@ # Page title -The `` component will automatically render the page title that corresponds with the title property set in the route record's meta field in `src/router/routes.js`. +The `` component will automatically render the page title that +corresponds with the title property set in the route record's meta field in +`src/router/routes.js`. ```js // src/router/routes.js @@ -13,11 +15,14 @@ The `` component will automatically render the page title that corre }, ``` -Optional page descriptions can be included by using the description prop `:description` prop and passing in the i18n localized text string. Translations are found in the `src/locales` folder. +Optional page descriptions can be included by using the description prop +`:description` prop and passing in the i18n localized text string. Translations +are found in the `src/locales` folder. ``` vue // Example: `src/views/AccessControl/Ldap/Ldap.vue` ``` -[View the page title component source code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageTitle.vue). +[View the page title component source +code](https://github.com/openbmc/webui-vue/blob/master/src/components/Global/PageTitle.vue). diff --git a/docs/guide/components/readme.md b/docs/guide/components/readme.md index f10a1317..aef688af 100644 --- a/docs/guide/components/readme.md +++ b/docs/guide/components/readme.md @@ -1,4 +1,10 @@ # Overview -Vue components are the building blocks of the OpenBMC Web UI. It uses both Boostrap-Vue components, as well as custom components. Using these components assures consistency throughout the application. They also improve the developer experience and increase efficiency. Review the existing components before using HTML markup. If the feature you're working on includes a new layout pattern, rather than adding raw markup to the page, consider creating a component that other sections of the application can use as well. +Vue components are the building blocks of the OpenBMC Web UI. It uses both +Boostrap-Vue components, as well as custom components. Using these components +assures consistency throughout the application. They also improve the developer +experience and increase efficiency. Review the existing components before using +HTML markup. If the feature you're working on includes a new layout pattern, +rather than adding raw markup to the page, consider creating a component that +other sections of the application can use as well. [Learn more about Vue components](https://vuejs.org/v2/guide/components.html) \ No newline at end of file diff --git a/docs/guide/components/status-icon/readme.md b/docs/guide/components/status-icon/readme.md index 0c9cc394..aef1f93c 100644 --- a/docs/guide/components/status-icon/readme.md +++ b/docs/guide/components/status-icon/readme.md @@ -1,6 +1,7 @@ # StatusIcon -The StatusIcon component is used to add an icon that represents one of the following statuses: +The StatusIcon component is used to add an icon that represents one of the +following statuses: - success - info diff --git a/docs/guide/components/table/index.md b/docs/guide/components/table/index.md index cd1ba202..614ef60f 100644 --- a/docs/guide/components/table/index.md +++ b/docs/guide/components/table/index.md @@ -1,11 +1,16 @@ # Table -All tables in the application are using the [BoostrapVue table component](https://bootstrap-vue.org/docs/components/table). +All tables in the application are using the [BoostrapVue table +component](https://bootstrap-vue.org/docs/components/table). -To use the component, include the `` tag in the template. The component is registered globally so does not need to be imported in each SFC. +To use the component, include the `` tag in the template. The component +is registered globally so does not need to be imported in each SFC. ## Basic table -There are a few required properties to maintain consistency across the application. The full list of options can be viewed on the [Bootstrap-vue table component's documentation page](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-props). +There are a few required properties to maintain consistency across the +application. The full list of options can be viewed on the [Bootstrap-vue table +component's documentation +page](https://bootstrap-vue.org/docs/components/table#comp-ref-b-table-props). ### Required properties @@ -13,12 +18,15 @@ There are a few required properties to maintain consistency across the applicati - `items` - renders table items - `fields` - renders table header - `hover` - enables table row hover state -- `responsive` or `stacked` - makes the table responsive (enables horizontal scrolling or stacked view) at the defined breakpoint -- `show-empty` *(required if table data is generated dynamically)* - shows an empty message if there are no items in the table -- `empty-text` *(required if table data is generated dynamically)* - the translated empty message +- `responsive` or `stacked` - makes the table responsive (enables horizontal + scrolling or stacked view) at the defined breakpoint +- `show-empty` *(required if table data is generated dynamically)* - shows an + empty message if there are no items in the table +- `empty-text` *(required if table data is generated dynamically)* - the + translated empty message -![Basic table example](./table.png) -![Basic empty table example](./table-empty.png) +![Basic table example](./table.png) ![Basic empty table +example](./table-empty.png) ```vue