Add htmlproofer to mkdocs

ansible · Feb 10, 2023 · e7da4e1 · e7da4e1
1 parent 26a12aa
commit e7da4e1
Show file tree

Hide file tree

Showing 14 changed files with 194 additions and 132 deletions.
diff --git a/.config/requirements-docs.txt b/.config/requirements-docs.txt
@@ -1,6 +1,7 @@
 cairosvg
 markdown-exec>=1.0.0
 mkdocs-gen-files>=0.4.0
+mkdocs-htmlproofer-plugin
 mkdocs-material-extensions>=1.1.1
 mkdocs-material>=9.0.6
 mkdocs>=1.4.2

diff --git a/.config/requirements.txt b/.config/requirements.txt
@@ -6,6 +6,7 @@
 #
 astroid==2.14.1
 attrs==22.2.0
+beautifulsoup4==4.11.2
 black==22.12.0
 bracex==2.3.post1
 cairocffi==1.4.0
@@ -45,6 +46,7 @@ mergedeep==1.3.4
 mkdocs==1.4.2
 mkdocs-autorefs==0.4.1
 mkdocs-gen-files==0.4.0
+mkdocs-htmlproofer-plugin==0.10.2
 mkdocs-material==9.0.11
 mkdocs-material-extensions==1.1.1
 mkdocstrings==0.20.0
@@ -79,6 +81,7 @@ rich==13.2.0
 ruamel-yaml==0.17.21
 setuptools==66.0.0
 six==1.16.0
+soupsieve==2.3.2.post1
 subprocess-tee==0.4.1
 tinycss2==1.2.1
 tomli==2.0.1

diff --git a/docs/configuring.md b/docs/configuring.md
@@ -47,10 +47,10 @@ Change **rev:** to either a commit sha or tag of Ansible-lint that contains
 `.pre-commit-hooks.yaml`.
 
 ```yaml
-- repo: https://github.com/ansible/ansible-lint.git
+- repo: https://github.com/ansible/ansible-lint
   rev: ... # put latest release tag from https://github.com/ansible/ansible-lint/releases/
   hooks:
     - id: ansible-lint
 ```
 
-[pre-commit]: https://pre-commit.com
+[pre-commit]: https://pre-commit.com/
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -59,7 +59,8 @@ As with all Ansible projects, we have a [Code of Conduct].
   https://docs.ansible.com/ansible/latest/community/communication.html
 [code of conduct]:
   https://docs.ansible.com/ansible/latest/community/code_of_conduct.html
-[creating your fork on github]: https://guides.github.com/activities/forking/
+[creating your fork on github]:
+  https://docs.github.com/en/get-started/quickstart/contributing-to-projects
 [discussions]: https://github.com/ansible/ansible-lint/discussions
 [supported ansible versions]:
   https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle

diff --git a/docs/index.md b/docs/index.md
@@ -16,7 +16,7 @@ community contributions and they can always be disabled based individually or by
 category by each user.
 
 [Ansible Galaxy project](https://github.com/ansible/galaxy/) makes use of this
-linter to compute quality scores for [Galaxy Hub](https://galaxy.ansible.com)
+linter to compute quality scores for [Galaxy Hub](https://galaxy.ansible.com/)
 contributed content. This does not mean this tool only targets those that want
 to share their code. Files like `galaxy.yml`, or sections like `galaxy_info`
 inside `meta.yml` help with documentation and maintenance, even for unpublished

diff --git a/docs/philosophy.md b/docs/philosophy.md
@@ -1,59 +1,109 @@
 # Philosophy of ansible-lint
 
-Ansible **playbooks, roles, and collections** should read like documentation, be production ready, unambiguous, and provide consistent results.
+Ansible **playbooks, roles, and collections** should read like documentation, be
+production ready, unambiguous, and provide consistent results.
 
-`Ansible-lint` should be considered a trusted advisor, helping ansible content creators write and package high-quality Ansible content. While not all rules may be applicable in all situations, they should be followed whenever possible.
+`Ansible-lint` should be considered a trusted advisor, helping ansible content
+creators write and package high-quality Ansible content. While not all rules may
+be applicable in all situations, they should be followed whenever possible.
 
-The goal of `ansible-lint` is to ensure that content created by different people has a similar look and feel. This makes the adoption and use of Ansible content easier in the community and enterprise. By keeping the number of configurable features at a minimum, consistent outcomes between authors can be achieved.
+The goal of `ansible-lint` is to ensure that content created by different people
+has a similar look and feel. This makes the adoption and use of Ansible content
+easier in the community and enterprise. By keeping the number of configurable
+features at a minimum, consistent outcomes between authors can be achieved.
 
 ## History and the future
 
-`ansible-lint` is almost a decade old, and its current list of rules is the result of a collaboration between many people. The tool originated as a community project and is currently part of the Ansible Galaxy submission and validation process.
+`ansible-lint` is almost a decade old, and its current list of rules is the
+result of a collaboration between many people. The tool originated as a
+community project and is currently part of the Ansible Galaxy submission and
+validation process.
 
-In the future, it will be an official component of the Red Hat Ansible Automation Platform, used during the collections certification process and the recommended Ansible content linter for Red Hat customers.
+In the future, it will be an official component of the Red Hat Ansible
+Automation Platform, used during the collections certification process and the
+recommended Ansible content linter for Red Hat customers.
 
-Starting in 2022, additional rules will be added that help content creators ready their content for production use. It will be through the use of ansible-lint and these rules, developers can have confidence their playbooks, roles, and task files are easy to understand and produce consistent results when run against anything, from servers in a home lab to mission-critical systems in the cloud.
+Starting in 2022, additional rules will be added that help content creators
+ready their content for production use. It will be through the use of
+ansible-lint and these rules, developers can have confidence their playbooks,
+roles, and task files are easy to understand and produce consistent results when
+run against anything, from servers in a home lab to mission-critical systems in
+the cloud.
 
 ## Style and formatting
 
-The focus of Ansible content creators should be on automation, outcomes and readability, rather than style or formatting. This is why we follow the same concepts as other code formatting tools like [black](https://github.com/psf/black) and [prettier](https://prettier.io).
+The focus of Ansible content creators should be on automation, outcomes and
+readability, rather than style or formatting. This is why we follow the same
+concepts as other code formatting tools like
+[black](https://github.com/psf/black) and [prettier](https://prettier.io/).
 
-Adoption of `ansible-lint` will save time by keeping reviews focused on the quality of the content and less so on the nuances of formatting and style.
+Adoption of `ansible-lint` will save time by keeping reviews focused on the
+quality of the content and less so on the nuances of formatting and style.
 
-As code formatting is not an art, we can save your project time and effort by applying a standardized code style and formatting.
+As code formatting is not an art, we can save your project time and effort by
+applying a standardized code style and formatting.
 
 ## Q&A
 
 ### Why does ansible-lint not accept all valid ansible syntax?
 
-`ansible-core` continues to mature while maintaining backward compatibility with early versions. `ansible-lint` has never intended to support the whole historical Ansible language syntax variations, but instead only the best of it.
+`ansible-core` continues to mature while maintaining backward compatibility with
+early versions. `ansible-lint` has never intended to support the whole
+historical Ansible language syntax variations, but instead only the best of it.
 
-It supports a broad vocabulary of keywords and styles. Over time, changes in the language have led to an improved experience for authors and consumers of Ansible content. The rules in `ansible-lint` suggest the use of these patterns.
+It supports a broad vocabulary of keywords and styles. Over time, changes in the
+language have led to an improved experience for authors and consumers of Ansible
+content. The rules in `ansible-lint` suggest the use of these patterns.
 
-It is these usage patterns that are written as rules in `ansible-lint`, leading to improved readability of **playbooks, roles**, and **collections**. The linter will always be more restrictive and opinionated regarding what it accepts. It is part of its design. We are not forced to keep the same backward compatibility level as Ansible, so we can tell people to avoid specific syntax for various reasons, such as being deprecated, unsafe, or hard to maintain.
+It is these usage patterns that are written as rules in `ansible-lint`, leading
+to improved readability of **playbooks, roles**, and **collections**. The linter
+will always be more restrictive and opinionated regarding what it accepts. It is
+part of its design. We are not forced to keep the same backward compatibility
+level as Ansible, so we can tell people to avoid specific syntax for various
+reasons, such as being deprecated, unsafe, or hard to maintain.
 
-Based on the extensive history of `ansible-lint` and user feedback, it notifies you about discouraged practices, sometimes before `ansible-core` starts doing so.
+Based on the extensive history of `ansible-lint` and user feedback, it notifies
+you about discouraged practices, sometimes before `ansible-core` starts doing
+so.
 
 ### What if I do not agree with a specific rule?
 
-We recognize that some projects will find at least one rule that might not suit their needs. Use the `skip_list` feature to temporarily bypass that rule until you have time to update your Ansible content.
+We recognize that some projects will find at least one rule that might not suit
+their needs. Use the `skip_list` feature to temporarily bypass that rule until
+you have time to update your Ansible content.
 
 ### Who decides which best practices get adopted in ansible-lint?
 
-The main source of new ideas was and remains our community. Before proposing a change, check with a few other Ansible users that work on different projects and see if they find it useful or not.
+The main source of new ideas was and remains our community. Before proposing a
+change, check with a few other Ansible users that work on different projects and
+see if they find it useful or not.
 
-It is better to get enough relevant feedback on our discussion forum before starting to implement new rules. If the proposed rule appears popular and does not conflict with existing rules, a core (maintainer) will tell you that the proposed rule can be added to ansible-lint, so you can start working on it without fear of rejection.
+It is better to get enough relevant feedback on our discussion forum before
+starting to implement new rules. If the proposed rule appears popular and does
+not conflict with existing rules, a core (maintainer) will tell you that the
+proposed rule can be added to ansible-lint, so you can start working on it
+without fear of rejection.
 
-The core team will decide on how a new rule will be added. Usually, they are added as experimental (warnings only) or even as opt-ins, being made implicit only when a major version is released.
+The core team will decide on how a new rule will be added. Usually, they are
+added as experimental (warnings only) or even as opt-ins, being made implicit
+only when a major version is released.
 
 ### Do I need to pass all rules to get my collection certified?
 
-Not really. The certification process is likely to use only a subset of rules. At this time, we are working on building that list.
+Not really. The certification process is likely to use only a subset of rules.
+At this time, we are working on building that list.
 
 ### Why lots of official Ansible docs examples are not passing linting?
 
-Most of the official examples are written to exemplify specific features, and some might conflict with our rules. Still, we plan to include linting of official examples in the future and add specific exclusions where needed, making it more likely that a copy/paste from the docs will not raise a bunch of linter violations.
+Most of the official examples are written to exemplify specific features, and
+some might conflict with our rules. Still, we plan to include linting of
+official examples in the future and add specific exclusions where needed, making
+it more likely that a copy/paste from the docs will not raise a bunch of linter
+violations.
 
 ### Why does ansible-lint require an Ansible version newer than what I use in production?
 
-Use `ansible-lint` as a **static analysis** tool for your content. You can run it with a version of ansible that is different than what you use in production. This helps you prepare your content for the future, so don't be afraid of using it in such a way.
+Use `ansible-lint` as a **static analysis** tool for your content. You can run
+it with a version of ansible that is different than what you use in production.
+This helps you prepare your content for the future, so don't be afraid of using
+it in such a way.
diff --git a/docs/profiles.md b/docs/profiles.md
@@ -18,44 +18,44 @@ The `min` profile ensures that Ansible can load content. Rules in this profile
 are mandatory because they prevent fatal errors. You can add files to the
 exclude list or provide dependencies to load the correct files.
 
-- [internal-error](rules/internal-error/)
-- [load-failure](rules/load-failure/)
-- [parser-error](rules/parser-error/)
-- [syntax-check](rules/syntax-check/)
+- [internal-error](rules/internal-error.md)
+- [load-failure](rules/load-failure.md)
+- [parser-error](rules/parser-error.md)
+- [syntax-check](rules/syntax-check.md)
 
 ## basic
 
 The `basic` profile prevents common coding issues and enforces standard styles
 and formatting. It extends [min](#min) profile.
 
-- [command-instead-of-module](rules/command-instead-of-module/)
-- [command-instead-of-shell](rules/command-instead-of-shell/)
-- [deprecated-bare-vars](rules/deprecated-bare-vars/)
-- [deprecated-command-syntax](rules/deprecated-command-syntax/)
-- [deprecated-local-action](rules/deprecated-local-action/)
-- [deprecated-module](rules/deprecated-module/)
-- [inline-env-var](rules/inline-env-var/)
-- [key-order](rules/key-order/)
-- [literal-compare](rules/literal-compare/)
-- [jinja](rules/jinja/)
-- [no-jinja-when](rules/no-jinja-when/)
-- [no-tabs](rules/no-tabs/)
-- [partial-become](rules/partial-become/)
-- [playbook-extension](rules/playbook-extension/)
-- [role-name](rules/role-name/)
-- [schema](rules/schema/)
-- [name](rules/name/)
-- [var-naming](rules/var-naming/)
-- [yaml](rules/yaml/)
+- [command-instead-of-module](rules/command-instead-of-module.md)
+- [command-instead-of-shell](rules/command-instead-of-shell.md)
+- [deprecated-bare-vars](rules/deprecated-bare-vars.md)
+- [deprecated-command-syntax](rules/deprecated-command-syntax.md)
+- [deprecated-local-action](rules/deprecated-local-action.md)
+- [deprecated-module](rules/deprecated-module.md)
+- [inline-env-var](rules/inline-env-var.md)
+- [key-order](rules/key-order.md)
+- [literal-compare](rules/literal-compare.md)
+- [jinja](rules/jinja.md)
+- [no-jinja-when](rules/no-jinja-when.md)
+- [no-tabs](rules/no-tabs.md)
+- [partial-become](rules/partial-become.md)
+- [playbook-extension](rules/playbook-extension.md)
+- [role-name](rules/role-name.md)
+- [schema](rules/schema.md)
+- [name](rules/name.md)
+- [var-naming](rules/var-naming.md)
+- [yaml](rules/yaml.md)
 
 ## moderate
 
 The `moderate` profile ensures that content adheres to best practices for making
 content easier to read and maintain. It extends [basic](#basic) profile.
 
-- [name[template]](rules/name/)
+- [name[template]](rules/name.md)
 - [name[imperative]](https://github.com/ansible/ansible-lint/issues/2170)
-- [name[casing]](rules/name/)
+- [name[casing]](rules/name.md)
 - [no-free-form](https://github.com/ansible/ansible-lint/issues/2117)
 - [spell-var-name](https://github.com/ansible/ansible-lint/issues/2168)
 
@@ -64,34 +64,34 @@ content easier to read and maintain. It extends [basic](#basic) profile.
 The `safety` profile avoids module calls that can have non-determinant outcomes
 or security concerns. It extends [moderate](#moderate) profile.
 
-- [avoid-implicit](/rules/avoid-implicit/)
-- [latest](/rules/latest/)
-- [package-latest](/rules/package-latest/)
-- [risky-file-permissions](/rules/risky-file-permissions/)
-- [risky-octal](/rules/risky-octal/)
-- [risky-shell-pipe](/rules/risky-shell-pipe/)
+- [avoid-implicit](rules/avoid-implicit.md)
+- [latest](rules/latest.md)
+- [package-latest](rules/package-latest.md)
+- [risky-file-permissions](rules/risky-file-permissions.md)
+- [risky-octal](rules/risky-octal.md)
+- [risky-shell-pipe](rules/risky-shell-pipe.md)
 
 ## shared
 
 The `shared` profile ensures that content follows best practices for packaging
 and publishing. This profile is intended for content creators who want to make
 Ansible playbooks, roles, or collections available from
-[galaxy.ansible.com](https://galaxy.ansible.com),
+[galaxy.ansible.com](https://galaxy.ansible.com/),
 [automation-hub](https://console.redhat.com/ansible/automation-hub), or a
 private instance. It extends [safety](#safety) profile.
 
-- [galaxy](/rules/galaxy/)
-- [ignore-errors](/rules/ignore-errors/)
+- [galaxy](rules/galaxy.md)
+- [ignore-errors](rules/ignore-errors.md)
 - [layout](https://github.com/ansible/ansible-lint/issues/1900)
-- [meta-incorrect](/rules/meta-incorrect/)
-- [meta-no-info](/rules/meta-no-info/)
-- [meta-no-tags](/rules/meta-no-tags/)
-- [meta-video-links](/rules/meta-video-links/)
+- [meta-incorrect](rules/meta-incorrect.md)
+- [meta-no-info](rules/meta-no-info.md)
+- [meta-no-tags](rules/meta-no-tags.md)
+- [meta-video-links](rules/meta-video-links.md)
 - [meta-version](https://github.com/ansible/ansible-lint/issues/2103)
-- [meta-runtime](/rules/meta-runtime/)
-- [no-changed-when](/rules/no-changed-when/)
-- [no-handler](/rules/no-handler/)
-- [no-relative-paths](/rules/no-relative-paths/)
+- [meta-runtime](rules/meta-runtime.md)
+- [no-changed-when](rules/no-changed-when.md)
+- [no-handler](rules/no-handler.md)
+- [no-relative-paths](rules/no-relative-paths.md)
 - [max-block-depth](https://github.com/ansible/ansible-lint/issues/2173)
 - [max-tasks](https://github.com/ansible/ansible-lint/issues/2172)
 - [unsafe-loop](https://github.com/ansible/ansible-lint/issues/2038)
@@ -105,7 +105,7 @@ as validated or certified content. It extends [shared](#shared) profile.
 
 - [avoid-dot-notation](https://github.com/ansible/ansible-lint/issues/2174)
 - [disallowed-ignore](https://github.com/ansible/ansible-lint/issues/2121)
-- [fqcn](/rules/fqcn/)
+- [fqcn](rules/fqcn.md)
 - [import-task-no-when](https://github.com/ansible/ansible-lint/issues/2219)
 - [meta-no-dependencies](https://github.com/ansible/ansible-lint/issues/2159)
 - [single-entry-point](https://github.com/ansible/ansible-lint/issues/2242)

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -147,6 +147,8 @@ plugins:
   - search
   - social
   - tags
+  # https://github.com/manuzhang/mkdocs-htmlproofer-plugin
+  # - htmlproofer
   - mkdocstrings:
       handlers:
         python:

diff --git a/src/ansiblelint/_internal/warning.md b/src/ansiblelint/_internal/warning.md
@@ -1,9 +1,10 @@
 # warning
 
 `warning` is a special type of internal rule that is used to report generic
-runtime warnings found during execution. As stated by its name, they are
-not counted as errors, so they do not influence the final outcome.
+runtime warnings found during execution. As stated by its name, they are not
+counted as errors, so they do not influence the final outcome.
 
 - `warning[empty-playbook]` is raised when a playbook file has no content.
-- `warning[raw-non-string]` indicates that you are using `[raw](http://docs.ansible.com/ansible/latest/collections/ansible/builtin/raw_module.html#ansible-collections-ansible-builtin-raw-module)` module with
-  non-string arguments, which is not supported by Ansible.
+- `warning[raw-non-string]` indicates that you are using
+  `[raw](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/raw_module.html#ansible-collections-ansible-builtin-raw-module)`
+  module with non-string arguments, which is not supported by Ansible.
diff --git a/src/ansiblelint/data/profiles.yml b/src/ansiblelint/data/profiles.yml
@@ -69,7 +69,7 @@ shared:
     The `shared` profile ensures that content follows best practices for packaging and publishing.
     This profile is intended for content creators who want to make Ansible
     playbooks, roles, or collections available from
-    [galaxy.ansible.com](https://galaxy.ansible.com),
+    [galaxy.ansible.com](https://galaxy.ansible.com/),
     [automation-hub](https://console.redhat.com/ansible/automation-hub),
     or a private instance.
   extends: safety