fix spelling and formatting of the docs

This commit is contained in:
Robert Kaussow 2020-06-03 16:23:46 +02:00
parent 2f838e359c
commit 7c6dfed431
16 changed files with 103 additions and 91 deletions

28
.dictionary Normal file
View File

@ -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

6
.markdownlint.yml Normal file
View File

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

View File

@ -3,20 +3,16 @@
[![Build Status](https://img.shields.io/drone/build/xoxys/ansible-later?logo=drone)](https://cloud.drone.io/xoxys/ansible-later) [![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) [![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/) [![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) [![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) [![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/). You can find the full documentation at [https://ansible-later.geekdocs.de](https://ansible-later.geekdocs.de/).

View File

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

View File

@ -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) [![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) [![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/) [![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) [![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) [![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). like [molecule](https://github.com/ansible/molecule).

View File

@ -2,11 +2,10 @@
title: Candidated 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 | | Object type | Description |
|-------------|------------------------------------------------------------------------------------------------------------------------------| | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Task | all files within the parent dir `tasks` | | Task | all files within the parent dir `tasks` |
| Handler | all files within the parent dir `handler` | | Handler | all files within the parent dir `handler` |
| RoleVars | all files within the parent dir `vars` or `default` | | RoleVars | all files within the parent dir `vars` or `default` |

View File

@ -4,6 +4,7 @@ title: Minimal standards checks
A typical standards check will look like: A typical standards check will look like:
<!-- prettier-ignore-start -->
{{< highlight Python "linenos=table" >}} {{< highlight Python "linenos=table" >}}
def check_playbook_for_something(candidate, settings): def check_playbook_for_something(candidate, settings):
result = Result(candidate.path) # empty result is a success with no output 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")) result.errors.append(Error(lineno+1, "Line is dodgy: reasons"))
return result return result
{{< /highlight >}} {{< /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`).

View File

@ -7,6 +7,7 @@ check those standards.
Create a file called standards.py (this can import other modules) Create a file called standards.py (this can import other modules)
<!-- prettier-ignore-start -->
{{< highlight Python "linenos=table" >}} {{< highlight Python "linenos=table" >}}
from ansiblelater include Standard, Result from ansiblelater include Standard, Result
@ -25,32 +26,28 @@ standards = [
role_must_contain_meta_main, role_must_contain_meta_main,
] ]
{{< /highlight >}} {{< /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" >}} {{< highlight INI "linenos=table" >}}
# Standards: 1.2 # Standards: 1.2
{{< /highlight >}} {{< /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" >}} {{< highlight Shell "linenos=table" >}}
git ls-files | xargs ansible-later -s "bare words are deprecated for with_items" git ls-files | xargs ansible-later -s "bare words are deprecated for with_items"
{{< /highlight >}} {{< /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.

View File

@ -2,19 +2,15 @@
title: Configuration 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.

View File

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

View File

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

View File

@ -2,11 +2,10 @@
title: Included rules 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 | | 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_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_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} | | check_yaml_hyphens | LINT0003 | YAML should use consitent number of spaces after hyphens (-). | {max-spaces-after: 1} |

View File

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

View File

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

View File

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

View File

@ -6,30 +6,18 @@ title: Usage
ansible-later FILES 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" >}} {{< highlight Shell "linenos=table" >}}
# Review single files # Review single files
ansible-later meta/main.yml tasks/install.yml ansible-later meta/main.yml tasks/install.yml
# Review all yml files (including subfolders) # Review all yml files (including sub-directories)
ansible-later **/*.yml ansible-later **/*.yml
{{< /highlight >}} {{< /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