diff --git a/.dictionary b/.dictionary new file mode 100644 index 0000000..606013d --- /dev/null +++ b/.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 diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..b59a114 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,6 @@ +--- +default: True +MD013: False +MD041: False +MD004: + style: dash diff --git a/README.md b/README.md index ad7de18..feb179d 100644 --- a/README.md +++ b/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 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/). diff --git a/ansiblelater/__main__.py b/ansiblelater/__main__.py index 045c6c0..08fa302 100755 --- a/ansiblelater/__main__.py +++ b/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" diff --git a/docs/content/_index.md b/docs/content/_index.md index 8ff9133..35dd521 100644 --- a/docs/content/_index.md +++ b/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 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). diff --git a/docs/content/build_rules/candidates.md b/docs/content/build_rules/candidates.md index 7fed8e4..d32c8de 100644 --- a/docs/content/build_rules/candidates.md +++ b/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 -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` | diff --git a/docs/content/build_rules/standards_check.md b/docs/content/build_rules/standards_check.md index 890e261..99a1f41 100644 --- a/docs/content/build_rules/standards_check.md +++ b/docs/content/build_rules/standards_check.md @@ -4,6 +4,7 @@ title: Minimal standards checks A typical standards check will look like: + {{< 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 >}} + -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`). diff --git a/docs/content/build_rules/standards_file.md b/docs/content/build_rules/standards_file.md index efb283c..163b9b7 100644 --- a/docs/content/build_rules/standards_file.md +++ b/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) + {{< highlight Python "linenos=table" >}} from ansiblelater include Standard, Result @@ -25,32 +26,28 @@ standards = [ role_must_contain_meta_main, ] {{< /highlight >}} + -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. + + {{< highlight INI "linenos=table" >}} # Standards: 1.2 {{< /highlight >}} + + -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. + {{< highlight Shell "linenos=table" >}} git ls-files | xargs ansible-later -s "bare words are deprecated for with_items" {{< /highlight >}} + -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. diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md index 3d7e5e9..c631f8c 100644 --- a/docs/content/configuration/_index.md +++ b/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, -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. diff --git a/docs/content/configuration/cli.md b/docs/content/configuration/cli.md index 70bc5c0..0d501c8 100644 --- a/docs/content/configuration/cli.md +++ b/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`: + {{< 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 >}} + diff --git a/docs/content/configuration/defaults.md b/docs/content/configuration/defaults.md index eea7dd8..37fa1c7 100644 --- a/docs/content/configuration/defaults.md +++ b/docs/content/configuration/defaults.md @@ -2,10 +2,12 @@ title: Default settings --- + + {{< 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 >}} + + diff --git a/docs/content/included_rules/_index.md b/docs/content/included_rules/_index.md index 39e14f4..ef4aed2 100644 --- a/docs/content/included_rules/_index.md +++ b/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 -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} | diff --git a/docs/content/setup/_index.md b/docs/content/setup/_index.md index caddedb..0e51640 100644 --- a/docs/content/setup/_index.md +++ b/docs/content/setup/_index.md @@ -1,4 +1,3 @@ --- title: Setup - --- diff --git a/docs/content/setup/pip.md b/docs/content/setup/pip.md index 4c6f6e5..65546b9 100644 --- a/docs/content/setup/pip.md +++ b/docs/content/setup/pip.md @@ -1,12 +1,15 @@ --- title: Using pip - --- + + {{< 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 >}} + + diff --git a/docs/content/setup/source.md b/docs/content/setup/source.md index 77aa4a5..a40fc73 100644 --- a/docs/content/setup/source.md +++ b/docs/content/setup/source.md @@ -1,11 +1,14 @@ --- title: From source - --- + + {{< 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 >}} + + diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index 5178c96..963bad4 100644 --- a/docs/content/usage/_index.md +++ b/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 -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: + + {{< 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 >}} + + -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.