mirror of
https://github.com/thegeeklab/ansible-later.git
synced 2024-11-21 12:20:40 +00:00
fix spelling and formatting of the docs
This commit is contained in:
parent
2f838e359c
commit
7c6dfed431
28
.dictionary
Normal file
28
.dictionary
Normal 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
6
.markdownlint.yml
Normal file
@ -0,0 +1,6 @@
|
||||
---
|
||||
default: True
|
||||
MD013: False
|
||||
MD041: False
|
||||
MD004:
|
||||
style: dash
|
||||
14
README.md
14
README.md
@ -3,20 +3,16 @@
|
||||
[](https://cloud.drone.io/xoxys/ansible-later)
|
||||
[](https://hub.docker.com/r/xoxys/ansible-later)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://codecov.io/gh/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/).
|
||||
|
||||
|
||||
@ -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"
|
||||
|
||||
@ -5,17 +5,14 @@ title: Documentation
|
||||
[](https://cloud.drone.io/xoxys/ansible-later)
|
||||
[](https://hub.docker.com/r/xoxys/ansible-later)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://pypi.org/project/ansible-later/)
|
||||
[](https://codecov.io/gh/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).
|
||||
|
||||
@ -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` |
|
||||
|
||||
@ -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`).
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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 -->
|
||||
|
||||
@ -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 -->
|
||||
|
||||
@ -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} |
|
||||
|
||||
@ -1,4 +1,3 @@
|
||||
---
|
||||
title: Setup
|
||||
|
||||
---
|
||||
|
||||
@ -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 -->
|
||||
|
||||
@ -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 -->
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user