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)
[![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 Release](https://img.shields.io/pypi/v/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/)
[![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
for his work on ansible-review and ansible-lint.
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.
_ansible-later_ is a best pratice scanner and linting tool. In most cases, if you write ansibel 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.
_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.
_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).
_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).
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():
"""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"

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)
[![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 Release](https://img.shields.io/pypi/v/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/)
[![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
for his work on ansible-review and ansible-lint.
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.
_ansible-later_ is a best pratice scanner and linting tool. In most cases, if you write ansibel 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.
_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.
_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).

View File

@ -2,11 +2,10 @@
title: Candidated
---
Each file passed to `ansible-later` will be classified. The result is a `Candidate` object
which contains some meta informations and is an instance of one of following object types.
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.
| 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` |

View File

@ -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.
The type can be inferred from the class name (i.e. `type(candidate).__name__`)
or from the table [here](#candidates).
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).
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`).
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`).

View File

@ -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.
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.
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.
<!-- 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
a message to be displayed but won't constitute a failure.
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.
When a standard version is higher than declared version, a message will be
displayed 'WARN: Future standard' and won't constitute a failure.
An example standards file is available at [ansiblelater/examples/standards.py](ansiblelater/examples/standards.py)
An example standards file is available at
[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.
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
`ansible-later` with the `-v` option.
You can see the name of the standards being checked for each different file by running `ansible-later` with the `-v` option.

View File

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

View File

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

View File

@ -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"
@ -44,7 +46,7 @@ rules:
# 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 -->

View File

@ -2,11 +2,10 @@
title: Included rules
---
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.
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.
| 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} |

View File

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

View File

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

View File

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

View File

@ -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
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:
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:
<!-- 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)
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
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.