docs: rule documentation harmonization

[MikeMcC399]

• supports resolution of issue cypress/no-async-before rule documentation issues #193

Issues

This PR deals with issues in the set of 9 docs/rules Markdown files.

1. The top-level headers of the docs/rules documents do not agree with the lib/rules property meta.docs.description.
2. Some headers do not include the name of the rule.
3. Formatting of the docs/rules documents is inconsistent.

Changes

1. Top-level headers of the docs/rules documents are built using the meta.docs.description property from the corresponding lib/rules source.
2. The docs/rules top-level header has the name of the rule in the form (cypress/<rule-name>) consistently appended.
3. Lower level headings and content are aligned with the Yeoman-based ESLint generator eslint/generator-eslint template _doc.md as follows:

- Rule Details
  - Options
- When Not To Use It
- Further Reading

4. Other grammatical text changes are made.
5. The documents are prepared for auto-generated content

Comments

• This PR only aims to restructure existing information.

• There is scope for further improvement of rule documents by adding content. For instance, the docs/rules/no-unnecessary-waiting.md essentially contains only a link to the Cypress documentation site without providing any other description or summary. This could optionally be covered in a later PR.

• Due to issues with the document generator incorrectly duplicating headers in some situations, the planned PR to add the npm module eslint-doc-generator is held back for the time being. The issues have been reported and PR OS-agnostic handling of end-of-line characters bmish/eslint-doc-generator#524 plans to address.

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[MikeMcC399]

Preview under

https://github.com/MikeMcC399/eslint-plugin-cypress/tree/rule-doc-harmonization/docs/rules

[jennifer-shehane]

Thanks for standardizing this. It's much better.

[MikeMcC399]

@jennifer-shehane

Thanks for standardizing this. It's much better.

It's taking shape bit by bit! Thanks for merging!

[cypress-app-bot]

🎉 This PR is included in version 3.0.3 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀