fix spelling and formatting of the docs

.dictionary

@@ -0,0 +1,28 @@
+([a-zA-Z0-9]+[_=])+\S+
+@\S+
+.py
+.yml
+CLI
+CONFIG_FILE
+config
+Codecov
+INI
+Kaussow
+PYTHONPATH
+PyPI
+YAML
+Ansible
+ansible-.+
+ansiblelater
+lineno
+sudo
+xargs
+yaml
+yamllint
+yml
+dotfiles
+parsable
+JSON
+reviewable
+changeset
+non-tty

.markdownlint.yml

@@ -0,0 +1,6 @@
+---
+default: True
+MD013: False
+MD041: False
+MD004:
+  style: dash

README.md

@@ -3,20 +3,16 @@
 [![Build Status](https://img.shields.io/drone/build/xoxys/ansible-later?logo=drone)](https://cloud.drone.io/xoxys/ansible-later)
 [![Docker Hub](https://img.shields.io/badge/docker-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/xoxys/ansible-later)
 [![Python Version](https://img.shields.io/pypi/pyversions/ansible-later.svg)](https://pypi.org/project/ansible-later/)
-[![PyPi Status](https://img.shields.io/pypi/status/ansible-later.svg)](https://pypi.org/project/ansible-later/)
+[![PyPI Status](https://img.shields.io/pypi/status/ansible-later.svg)](https://pypi.org/project/ansible-later/)
-[![PyPi Release](https://img.shields.io/pypi/v/ansible-later.svg)](https://pypi.org/project/ansible-later/)
+[![PyPI Release](https://img.shields.io/pypi/v/ansible-later.svg)](https://pypi.org/project/ansible-later/)
 [![Codecov](https://img.shields.io/codecov/c/github/xoxys/ansible-later)](https://codecov.io/gh/xoxys/ansible-later)
 [![License: MIT](https://img.shields.io/github/license/xoxys/ansible-later)](LICENSE)
 
-This is a fork of Will Thames [ansible-review](https://github.com/willthames/ansible-review) so credits goes to him
+This is a fork of Will Thames [ansible-review](https://github.com/willthames/ansible-review) so credits goes to him for his work on ansible-review and ansible-lint.
-for his work on ansible-review and ansible-lint.
 
-_ansible-later_ is a best pratice scanner and linting tool. In most cases, if you write ansibel roles in a team,
+_ansible-later_ is a best practice scanner and linting tool. In most cases, if you write Ansible roles in a team, it helps to have a coding or best practice guideline in place. This will make Ansible roles more readable for all maintainers and can reduce the troubleshooting time.
-it helps to have a coding or best practice guideline in place. This will make ansible roles more readable for all
-maintainers and can reduce the troubleshooting time.
 
-_ansible-later_ does __not__ ensure that your role will work as expected. For Deployment test you can use other tools
+_ansible-later_ does __not__ ensure that your role will work as expected. For Deployment test you can use other tools like [molecule](https://github.com/ansible/molecule).
-like [molecule](https://github.com/ansible/molecule).
 
 You can find the full documentation at [https://ansible-later.geekdocs.de](https://ansible-later.geekdocs.de/).
 

ansiblelater/__main__.py

@@ -15,7 +15,7 @@ from ansiblelater.command import candidates
 def main():
     """Run main program."""
     parser = argparse.ArgumentParser(
-        description="Validate ansible files against best pratice guideline"
+        description="Validate Ansible files against best practice guideline"
     )
     parser.add_argument(
         "-c", "--config", dest="config_file", help="location of configuration file"

docs/content/_index.md

@@ -5,17 +5,14 @@ title: Documentation
 [![Build Status](https://img.shields.io/drone/build/xoxys/ansible-later?logo=drone)](https://cloud.drone.io/xoxys/ansible-later)
 [![Docker Hub](https://img.shields.io/badge/docker-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/xoxys/ansible-later)
 [![Python Version](https://img.shields.io/pypi/pyversions/ansible-later.svg)](https://pypi.org/project/ansible-later/)
-[![PyPi Status](https://img.shields.io/pypi/status/ansible-later.svg)](https://pypi.org/project/ansible-later/)
+[![PyPI Status](https://img.shields.io/pypi/status/ansible-later.svg)](https://pypi.org/project/ansible-later/)
-[![PyPi Release](https://img.shields.io/pypi/v/ansible-later.svg)](https://pypi.org/project/ansible-later/)
+[![PyPI Release](https://img.shields.io/pypi/v/ansible-later.svg)](https://pypi.org/project/ansible-later/)
 [![Codecov](https://img.shields.io/codecov/c/github/xoxys/ansible-later)](https://codecov.io/gh/xoxys/ansible-later)
 [![License: MIT](https://img.shields.io/github/license/xoxys/ansible-later)](https://github.com/xoxys/ansible-later/blob/master/LICENSE)
 
-This is a fork of Will Thames [ansible-review](https://github.com/willthames/ansible-review) so credits goes to him
+This is a fork of Will Thames [ansible-review](https://github.com/willthames/ansible-review) so credits goes to him for his work on ansible-review and ansible-lint.
-for his work on ansible-review and ansible-lint.
 
-_ansible-later_ is a best pratice scanner and linting tool. In most cases, if you write ansibel roles in a team,
+_ansible-later_ is a best practice scanner and linting tool. In most cases, if you write Ansible roles in a team, it helps to have a coding or best practice guideline in place. This will make Ansible roles more readable for all maintainers and can reduce the troubleshooting time.
-it helps to have a coding or best practice guideline in place. This will make ansible roles more readable for all
-maintainers and can reduce the troubleshooting time.
 
-_ansible-later_ does __not__ ensure that your role will work as expected. For Deployment test you can use other tools
+_ansible-later_ does **not** ensure that your role will work as expected. For Deployment test you can use other tools
 like [molecule](https://github.com/ansible/molecule).

docs/content/build_rules/candidates.md

@@ -2,11 +2,10 @@
 title: Candidated
 ---
 
-Each file passed to `ansible-later` will be classified. The result is a `Candidate` object
+Each file passed to `ansible-later` will be classified. The result is a `Candidate` object which contains some meta information and is an instance of one of following object types.
-which contains some meta informations and is an instance of one of following object types.
 
 | Object type | Description                                                                                                                  |
-|-------------|------------------------------------------------------------------------------------------------------------------------------|
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | Task        | all files within the parent dir `tasks`                                                                                      |
 | Handler     | all files within the parent dir `handler`                                                                                    |
 | RoleVars    | all files within the parent dir `vars` or `default`                                                                          |

docs/content/build_rules/standards_check.md

@@ -4,6 +4,7 @@ title: Minimal standards checks
 
 A typical standards check will look like:
 
+<!-- prettier-ignore-start -->
 {{< highlight Python "linenos=table" >}}
 def check_playbook_for_something(candidate, settings):
     result = Result(candidate.path) # empty result is a success with no output
@@ -14,14 +15,8 @@ def check_playbook_for_something(candidate, settings):
                 result.errors.append(Error(lineno+1, "Line is dodgy: reasons"))
     return result
 {{< /highlight >}}
+<!-- prettier-ignore-end -->
 
-All standards check take a candidate object, which has a path attribute.
+All standards check take a candidate object, which has a path attribute. The type can be inferred from the class name (i.e. `type(candidate).__name__`) or from the table [here](#candidates).
-The type can be inferred from the class name (i.e. `type(candidate).__name__`)
-or from the table [here](#candidates).
 
-They return a `Result` object, which contains a possibly empty list of `Error`
+They return a `Result` object, which contains a possibly empty list of `Error` objects. `Error` objects are formed of a line number and a message. If the error applies to the whole file being reviewed, set the line number to `None`. Line numbers are important as `ansible-later` can review just ranges of files to only review changes (e.g. through piping the output of `git diff` to `ansible-later`).
-objects. `Error` objects are formed of a line number and a message. If the
-error applies to the whole file being reviewed, set the line number to `None`.
-Line numbers are important as `ansible-later` can review just ranges of files
-to only review changes (e.g. through piping the output of `git diff` to
-`ansible-later`).

docs/content/build_rules/standards_file.md

@@ -7,6 +7,7 @@ check those standards.
 
 Create a file called standards.py (this can import other modules)
 
+<!-- prettier-ignore-start -->
 {{< highlight Python "linenos=table" >}}
 from ansiblelater include Standard, Result
 
@@ -25,32 +26,28 @@ standards = [
   role_must_contain_meta_main,
 ]
 {{< /highlight >}}
+<!-- prettier-ignore-end -->
 
-When you add new standards, you should increment the version of your standards.
+When you add new standards, you should increment the version of your standards. Your playbooks and roles should declare what version of standards you are using, otherwise ansible-later assumes you're using the latest. The declaration is done by adding standards version as first line in the file.
-Your playbooks and roles should declare what version of standards you are
-using, otherwise ansible-later assumes you're using the latest. The declaration
-is done by adding standards version as first line in the file. e.g.
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 {{< highlight INI "linenos=table" >}}
 # Standards: 1.2
 {{< /highlight >}}
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
 
-To add standards that are advisory, don't set the version. These will cause
+To add standards that are advisory, don't set the version. These will cause a message to be displayed but won't constitute a failure. When a standard version is higher than declared version, a message will be displayed 'WARN: Future standard' and won't constitute a failure.
-a message to be displayed but won't constitute a failure.
 
-When a standard version is higher than declared version, a message will be
+An example standards file is available at [ansiblelater/examples/standards.py](ansiblelater/examples/standards.py)
-displayed 'WARN: Future standard' and won't constitute a failure.
 
-An example standards file is available at
+If you only want to check one or two standards quickly (perhaps you want to review your entire code base for deprecated bare words), you can use the `-s` flag with the name of your standard. You can pass `-s` multiple times.
-[ansiblelater/examples/standards.py](ansiblelater/examples/standards.py)
-
-If you only want to check one or two standards quickly (perhaps you want
-to review your entire code base for deprecated bare words), you can use the
-`-s` flag with the name of your standard. You can pass `-s` multiple times.
 
+<!-- prettier-ignore-start -->
 {{< highlight Shell "linenos=table" >}}
 git ls-files | xargs ansible-later -s "bare words are deprecated for with_items"
 {{< /highlight >}}
+<!-- prettier-ignore-end -->
 
-You can see the name of the standards being checked for each different file by running
+You can see the name of the standards being checked for each different file by running `ansible-later` with the `-v` option.
-`ansible-later` with the `-v` option.

docs/content/configuration/_index.md

@@ -2,19 +2,15 @@
 title: Configuration
 ---
 
-ansible-later comes with some default settigs which should be sufficent for most users to start,
+ansible-later comes with some default settings which should be sufficient for most users to start, but you can adjust most settings to your needs.
-but you can adjust most settings to your needs.
 
-Changes can be made in a yaml configuration file or through cli options
+Changes can be made in a yaml configuration file or through CLI options which will be processed in the following order (last wins):
-which will be processed in the following order (last wins):
 
-- default config (build-in)
+- default configuration (build-in)
-- global config file (this will depend on your operating system)
+- global configuration file (this will depend on your operating system)
-- folderbased config file (`.later.yml` file in current working folder)
+- directory based configuration file (`.later.yml` file in current working directory)
-- cli options
+- CLI options
 
-Be careful! YAML Attributes will be overwritten while lists in any
+Be careful! YAML Attributes will be overwritten while lists in any configuration file will be merged.
-config file will be merged.
 
-To make it easier to review a singel file e.g. for debugging purpose, amsible-later
+To make it easier to review a single file e.g. for debugging purpose, ansible-later will ignore `exclude_files` and `ignore_dotfiles` options.
-will ignore `exclude_files` and `ignore_dotfiles` options.

docs/content/configuration/cli.md

@@ -2,15 +2,16 @@
 title: CLI options
 ---
 
-You can get all available cli options by running `ansible-later --help`:
+You can get all available CLI options by running `ansible-later --help`:
 
+<!-- prettier-ignore-start -->
 {{< highlight Shell "linenos=table" >}}
 $ ansible-later --help
 usage: ansible-later [-h] [-c CONFIG_FILE] [-r RULES.STANDARDS]
                      [-s RULES.FILTER] [-v] [-q] [--version]
                      [rules.files [rules.files ...]]
 
-Validate ansible files against best pratice guideline
+Validate Ansible files against best practice guideline
 
 positional arguments:
   rules.files
@@ -29,3 +30,4 @@ optional arguments:
   -q                    decrease log level
   --version             show program's version number and exit
 {{< /highlight >}}
+<!-- prettier-ignore-end -->

docs/content/configuration/defaults.md

@@ -2,10 +2,12 @@
 title: Default settings
 ---
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 {{< highlight YAML "linenos=table" >}}
 ---
 ansible:
-  # Add the name of used custom ansible modules.
+  # Add the name of used custom Ansible modules.
   # Otherwise ansible-later can't detect unknown modules
   # and will through an error.
   custom_modules: []
@@ -16,9 +18,9 @@ ansible:
 
 # Global logging configuration
 # If you would like to force colored output (e.g. non-tty)
-# set emvironment variable `PY_COLORS=1`
+# set environment variable `PY_COLORS=1`
 logging:
-  # You can enable json logging if a parsable output is required
+  # You can enable JSON logging if a parsable output is required
   json: False
   # Possible options debug | info | warning | error | critical
   level: "warning"
@@ -37,14 +39,14 @@ rules:
 
   # Exclude given rule ID's from checks
   exclude_filter: []
-  
+
   # All dotfiles (including hidden folders) are excluded by default.
   # You can disable this setting and handle dotfiles by yourself with `exclude_files`.
   ignore_dotfiles: True
   # Path to the folder containing your custom standards file
   standards: ansiblelater/data
 
-# Block to control included yamlllint rules.
+# Block to control included yamllint rules.
 # See https://yamllint.readthedocs.io/en/stable/rules.html
 yamllint:
   colons:
@@ -63,3 +65,5 @@ yamllint:
     indent-sequences: True
     spaces: 2
 {{< /highlight >}}
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->

docs/content/included_rules/_index.md

@@ -2,11 +2,10 @@
 title: Included rules
 ---
 
-Reviews are nothing without some rules or standards against which to review. ansible-later
+Reviews are nothing without some rules or standards against which to review. ansible-later comes with a couple of built-in checks explained in the following table.
-comes with a couple of built-in checks explained in the following table.
 
 | Rule                            | ID          | Description                                                       | Parameter                                                            |
-|---------------------------------|-------------|-------------------------------------------------------------------|----------------------------------------------------------------------|
+| ------------------------------- | ----------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
 | check_yaml_empty_lines          | LINT0001    | YAML should not contain unnecessarily empty lines.                | {max: 1, max-start: 0, max-end: 1}                                   |
 | check_yaml_indent               | LINT0002    | YAML should be correctly indented.                                | {spaces: 2, check-multi-line-strings: false, indent-sequences: true} |
 | check_yaml_hyphens              | LINT0003    | YAML should use consitent number of spaces after hyphens (-).     | {max-spaces-after: 1}                                                |

docs/content/setup/_index.md

@@ -1,4 +1,3 @@
 ---
 title: Setup
-
 ---

docs/content/setup/pip.md

@@ -1,12 +1,15 @@
 ---
 title: Using pip
-
 ---
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 {{< highlight Shell "linenos=table" >}}
-# From internal pip repo as user
+# From pip as user
 pip install ansible-later --user
 
 # .. or as root
 sudo pip install ansible-later
 {{< /highlight >}}
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->

docs/content/setup/source.md

@@ -1,11 +1,14 @@
 ---
 title: From source
-
 ---
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 {{< highlight Shell "linenos=table" >}}
 # Install dependency
 git clone https://github.com/xoxys/ansible-later
 export PYTHONPATH=$PYTHONPATH:`pwd`/ansible-later/ansiblelater
 export PATH=$PATH:`pwd`/ansible-later/bin
 {{< /highlight >}}
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->

docs/content/usage/_index.md

@@ -6,30 +6,18 @@ title: Usage
 ansible-later FILES
 ```
 
-If you don't pass any file to ansible-later it will review all files including subdirs in
+If you don't pass any file to ansible-later it will review all files including sub-directories in the current working directory (hidden files and folders are excluded by default). Otherwise you can pass a space delimited list of files to review. You can also pass glob patterns to ansible-later:
-the current working directory (hidden files and folders are excluded by default).
-
-Otherwise you can pass a space delimited list of files to review. You can also pass glob
-patterns to ansible-later:
 
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
 {{< highlight Shell "linenos=table" >}}
 # Review single files
 ansible-later meta/main.yml tasks/install.yml
 
-# Review all yml files (including subfolders)
+# Review all yml files (including sub-directories)
 ansible-later **/*.yml
 {{< /highlight >}}
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
 
-ansible-later will review inventory files, role files, python code (modules, plugins)
+ansible-later will review inventory files, role files, python code (modules, plugins) and playbooks. The goal is that each file that changes in a changeset should be reviewable simply by passing those files as the arguments to ansible-later.
-and playbooks.
-
-- The goal is that each file that changes in a
-  changeset should be reviewable simply by passing
-  those files as the arguments to ansible-later.
-- Using `{{ playbook_dir }}` in sub roles is so far
-  very hard.
-- This should work against various repository styles
-  - per-role repository
-  - roles with sub-roles
-  - per-playbook repository
-- It should work with roles requirement files and with local roles