diff --git a/.config/dictionary.txt b/.config/dictionary.txt index 1b633b2bca..d32df04fa9 100644 --- a/.config/dictionary.txt +++ b/.config/dictionary.txt @@ -47,6 +47,7 @@ autodetected autodiscovery autodoc autofix +autorefs autoupdate awcrosby backports @@ -118,6 +119,7 @@ ematchtestfile envrc execnet extlinks +facelessuser facter fakerole fileglob @@ -126,6 +128,7 @@ filesspot filetree fips firewalld +fontawesome formatstr formetting formsyntax @@ -149,8 +152,8 @@ hwcksum idempotency importlib iniconfig +inlinehilite insertafter -intersphinx ipwrap isclass iscsi @@ -173,12 +176,14 @@ libbzip libera libyaml lineinfile +linenums linkcheck lintable lintables literalinclude localectl machinectl +magiclink markdownlint matchdir matcherror @@ -191,6 +196,7 @@ maxdepth minversion mkdir mkdocs +mkdocstrings mkdtemp mockings mockreturn @@ -247,6 +253,8 @@ pyenv pygments pylint pylintrc +pymdown +pymdownx pypa pyparsing pypi @@ -296,7 +304,6 @@ skiputils slaveinput sortfunc sourcegraph -sphinxcontrib srpm ssbarnea stylesheet @@ -307,6 +314,7 @@ subschema subschemas substrs subtest +superfences supervisorctl synchronize sysvinit diff --git a/.config/requirements-docs.txt b/.config/requirements-docs.txt index 03e0b588a7..60cbdaf6a9 100644 --- a/.config/requirements-docs.txt +++ b/.config/requirements-docs.txt @@ -1,8 +1,11 @@ -myst-parser >= 0.16.1 -pipdeptree >= 2.2.1 -sphinx >= 4.4.0 -sphinx-ansible-theme >= 0.9.1 -sphinx-rtd-theme >= 1.0.0, < 2.0.0 # 1.0.0 broke rendering -sphinxcontrib-apidoc >= 0.3.0 -sphinxcontrib-programoutput2 >= 2.0a1 - +cairosvg +markdown-exec>=1.0.0 +mkdocs-gen-files>=0.4.0 +mkdocs-material-extensions>=1.1.1 +mkdocs-material>=9.0.6 +mkdocs>=1.4.2 +mkdocstrings-python>=0.8.3 +mkdocstrings>=0.20.0 +pillow +pipdeptree>=2.3.3 +pymdown-extensions>=9.9.2 diff --git a/.config/requirements.txt b/.config/requirements.txt index c273a5d80e..48237b167e 100644 --- a/.config/requirements.txt +++ b/.config/requirements.txt @@ -4,47 +4,57 @@ # # pip-compile --extra=docs --extra=test --no-annotate --output-file=.config/requirements.txt --resolver=backtracking --strip-extras --unsafe-package=ansible-core pyproject.toml # -alabaster==0.7.13 ansible-compat==2.2.7 -ansible-pygments==0.1.1 astroid==2.13.2 attrs==22.2.0 -babel==2.11.0 black==22.12.0 bracex==2.3.post1 +cairocffi==1.4.0 +cairosvg==2.6.0 certifi==2022.12.7 cffi==1.15.1 charset-normalizer==3.0.1 click==8.1.3 +colorama==0.4.6 coverage==7.0.5 coverage-enable-subprocess==1.0 cryptography==39.0.0 +cssselect2==0.7.0 +defusedxml==0.7.1 dill==0.3.6 -docutils==0.17.1 exceptiongroup==1.1.0 execnet==1.9.0 filelock==3.9.0 flake8==6.0.0 flake8-future-annotations==1.0.0 +ghp-import==2.1.0 +griffe==0.25.4 idna==3.4 -imagesize==1.4.1 importlib-metadata==6.0.0 iniconfig==2.0.0 isort==5.11.4 jinja2==3.1.2 jsonschema==4.17.3 lazy-object-proxy==1.9.0 +markdown==3.3.7 +markdown-exec==1.0.0 markdown-it-py==2.1.0 markupsafe==2.1.1 mccabe==0.7.0 -mdit-py-plugins==0.3.3 mdurl==0.1.2 +mergedeep==1.3.4 +mkdocs==1.4.2 +mkdocs-autorefs==0.4.1 +mkdocs-gen-files==0.4.0 +mkdocs-material==9.0.6 +mkdocs-material-extensions==1.1.1 +mkdocstrings==0.20.0 +mkdocstrings-python==0.8.3 mypy==0.991 mypy-extensions==0.4.3 -myst-parser==0.18.1 packaging==23.0 pathspec==0.10.3 -pbr==5.11.1 +pillow==9.4.0 pipdeptree==2.3.3 platformdirs==2.6.2 pluggy==1.0.0 @@ -54,37 +64,32 @@ pycparser==2.21 pyflakes==3.0.1 pygments==2.14.0 pylint==2.15.10 +pymdown-extensions==9.9.2 pyrsistent==0.19.3 pytest==7.2.1 pytest-mock==3.10.0 pytest-plus==0.4.0 pytest-xdist==3.1.0 -pytz==2022.7.1 +python-dateutil==2.8.2 pyyaml==6.0 +pyyaml-env-tag==0.1 +regex==2022.10.31 requests==2.28.2 resolvelib==0.8.1 rich==13.2.0 ruamel-yaml==0.17.21 ruamel-yaml-clib==0.2.7 setuptools==66.0.0 -snowballstemmer==2.2.0 -sphinx==5.3.0 -sphinx-ansible-theme==0.10.1 -sphinx-rtd-theme==1.1.1 -sphinxcontrib-apidoc==0.3.0 -sphinxcontrib-applehelp==1.0.3 -sphinxcontrib-devhelp==1.0.2 -sphinxcontrib-htmlhelp==2.0.0 -sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-programoutput2==2.0a1 -sphinxcontrib-qthelp==1.0.3 -sphinxcontrib-serializinghtml==1.1.5 +six==1.16.0 subprocess-tee==0.4.1 +tinycss2==1.2.1 tomli==2.0.1 tomlkit==0.11.6 typing-extensions==4.4.0 urllib3==1.26.14 +watchdog==2.2.1 wcmatch==8.4.1 +webencodings==0.5.1 wrapt==1.14.1 yamllint==1.29.0 zipp==3.11.0 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md deleted file mode 100644 index f9781070b5..0000000000 --- a/.github/CONTRIBUTING.md +++ /dev/null @@ -1,63 +0,0 @@ -# Contributing to Ansible-lint - -To contribute to ansible-lint, please use pull requests on a branch -of your own fork. - -After [creating your fork on GitHub], you can do: - -```shell-session -$ git clone git@github.com:your-name/ansible-lint -$ cd ansible-lint -$ git checkout -b your-branch-name -# DO SOME CODING HERE -$ git add your new files -$ git commit -v -$ git push origin your-branch-name -``` - -You will then be able to create a pull request from your commit. - -All fixes to core functionality (i.e. anything except docs or examples) -should be accompanied by tests that fail prior to your change and -succeed afterwards. - -Feel free to raise issues in the repo if you feel unable to -contribute a code fix. - -## Standards - -ansible-lint is flake8 compliant with **max-line-length** set to 100. - -ansible-lint works only with supported Ansible versions at the time it was released. - -Automated tests will be run against all PRs for flake8 compliance -and Ansible compatibility — to check before pushing commits, just -use [tox](https://tox.wiki/en/latest/). - -% DO-NOT-REMOVE-deps-snippet-PLACEHOLDER - -## Talk to us - -Use Github [discussions] forum or for a live chat experience try -`#ansible-devtools` IRC channel on libera.chat or Matrix room -[#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com). - -For the full list of Ansible IRC and Mailing list, please see the -[Ansible Communication] page. -Release announcements will be made to the [Ansible Announce] list. - -Possible security bugs should be reported via email -to . - -## Code of Conduct - -As with all Ansible projects, we have a [Code of Conduct]. - -[.flake8]: https://github.com/ansible/ansible-lint/blob/main/.flake8 -[ansible announce]: https://groups.google.com/forum/#!forum/ansible-announce -[ansible communication]: https://docs.ansible.com/ansible/latest/community/communication.html -[code of conduct]: https://docs.ansible.com/ansible/latest/community/code_of_conduct.html -[creating your fork on github]: https://guides.github.com/activities/forking/ -[discussions]: https://github.com/ansible/ansible-lint/discussions -[supported ansible versions]: https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle -[tox]: https://tox.readthedocs.io diff --git a/.gitignore b/.gitignore index 81fb714dcc..e082ca2b0c 100644 --- a/.gitignore +++ b/.gitignore @@ -64,7 +64,8 @@ src/ansiblelint/_version.py .pytest_cache test/eco/CODENOTIFY.html test/eco -docs/profiles.md test/schemas/node_modules .envrc collections +site +_readthedocs diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0bdd002602..57006b3a00 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -198,7 +198,6 @@ repos: - pyyaml - rich>=13.2.0 - ruamel.yaml - - sphinx - typing_extensions - wcmatch - yamllint diff --git a/.readthedocs.yml b/.readthedocs.yml index 1cfd9b82ec..ac4348604c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,52 +1,23 @@ -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html -# for details - --- -# Required version: 2 -# Build documentation in the docs/ directory with Sphinx -sphinx: - # keep dirhtml for nice URLs without .html extension - builder: dirhtml - configuration: docs/conf.py +mkdocs: fail_on_warning: true - -# Build documentation with MkDocs -#mkdocs: -# configuration: mkdocs.yml -# fail_on_warning: true - -# Optionally build your docs in additional formats -# such as PDF and ePub -formats: [] - -submodules: - include: all # [] - exclude: [] - recursive: true + configuration: mkdocs.yml build: - # when using pre_build, "image:" is not supported and os and tools are required os: ubuntu-22.04 tools: - python: "3.10" - jobs: - pre_build: - - pip install '.[docs,test]' - - ansible-lint -L -f docs -# Optionally set the version of Python and requirements required -# to build docs -# python: -# version: "3.9" -# install: -# # On https://readthedocs.org/dashboard/ansible-lint/environmentvariables/ we -# # do have PIP_CONSTRAINTS=.config/requirements.txt which ensures we install only -# # pinned requirements that that we know to be working. -# - method: pip -# path: . -# extra_requirements: -# - docs -# - test -# system_packages: false + python: "3.11" + commands: + - pip install --user tox + - python3 -m tox -e docs -- --strict --site-dir=_readthedocs/html/ +python: + system_packages: false + install: + - method: pip + path: tox + - method: pip + path: . + extra_requirements: + - docs diff --git a/a.ansi b/a.ansi new file mode 100644 index 0000000000..62588d28c6 --- /dev/null +++ b/a.ansi @@ -0,0 +1 @@ +Hello World diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index b84f66817e..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Documentation source for Ansible Lint - -To build the docs, run `tox -e docs`. At the end of the build, you will -see the local location of your built docs. - -Building docs locally may not be identical to CI/CD builds. We recommend -you to create a draft PR and check the RTD PR preview page too. - -If you do not want to learn the reStructuredText format, you can also [file an issue](https://github.com/ansible/ansible-lint/issues), and let us know how we can improve our documentation. diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 98eee82896..0000000000 --- a/docs/conf.py +++ /dev/null @@ -1,338 +0,0 @@ -# -# documentation build configuration file, created by -# sphinx-quickstart on Sat Sep 27 13:23:22 2008-2009. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed -# automatically). -# -# All configuration values have a default value; values that are commented out -# serve to show the default value. -"""Documentation Configuration.""" -# pylint: disable=invalid-name -from __future__ import annotations - -import os -import sys -from pathlib import Path - -import pkg_resources - -# Make in-tree extension importable in non-tox setups/envs, like RTD. -# Refs: -# https://github.com/readthedocs/readthedocs.org/issues/6311 -# https://github.com/readthedocs/readthedocs.org/issues/7182 -sys.path.insert(0, str(Path(__file__).parent.resolve())) - -# pip3 install sphinx_rtd_theme -# import sphinx_rtd_theme -# html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] - -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. -# sys.path.append(os.path.abspath('some/directory')) -# -sys.path.insert(0, os.path.join("ansible", "lib")) -sys.path.append(os.path.abspath("_themes")) - -VERSION = "latest" -AUTHOR = "Ansible, Inc" - -# General configuration -# --------------------- - -# Add any Sphinx extension module names here, as strings. -# They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -# TEST: 'sphinxcontrib.fulltoc' -extensions = [ - "myst_parser", - "sphinx.ext.autodoc", - "sphinx.ext.intersphinx", - # Third-party extensions: - "sphinxcontrib.apidoc", - "sphinxcontrib.programoutput", -] - - -# Fail safe protection to detect conflicting packages -try: - pkg_resources.get_distribution("sphinxcontrib-programoutput") - # flake8: noqa: T201 - print( - "FATAL: We detected presence of sphinxcontrib-programoutput package instead of sphinxcontrib-programoutput2 one. You must be sure the first is not installed.", - file=sys.stderr, - ) - sys.exit(2) -except pkg_resources.DistributionNotFound: - pass - -# Later on, add 'sphinx.ext.viewcode' to the list if you want to have -# colorized code generated too for references. - - -# Add any paths that contain templates here, relative to this directory. -templates_path = [".templates"] - -# The suffix of source filenames. -source_suffix = { - ".rst": "restructuredtext", - ".md": "markdown", -} - -# The master toctree document. -master_doc = "index" - -apidoc_excluded_paths: list[str] = [] -apidoc_extra_args = [ - "--implicit-namespaces", - "--private", # include “_private” modules -] -apidoc_module_dir = "../src/ansiblelint" -apidoc_module_first = False -apidoc_output_dir = "pkg" -apidoc_separate_modules = True -apidoc_toc_file: str | None = None - -# General substitutions. -project = "Ansible Lint Documentation" -copyright = "Ansible Lint project contributors" # pylint: disable=redefined-builtin - -github_url = "https://github.com" -github_repo_org = "ansible" -github_repo_name = "ansible-lint" -github_repo_slug = f"{github_repo_org}/{github_repo_name}" -github_repo_url = f"{github_url}/{github_repo_slug}" - -extlinks = { - "issue": (f"{github_repo_url}/issues/%s", "#"), - "pr": (f"{github_repo_url}/pull/%s", "PR #"), - "commit": (f"{github_repo_url}/commit/%s", ""), - "gh": (f"{github_url}/%s", "GitHub: "), -} - -intersphinx_mapping = { - "ansible": ("https://docs.ansible.com/ansible/devel/", None), - "ansible-core": ("https://docs.ansible.com/ansible-core/devel/", None), - "packaging": ("https://packaging.pypa.io/en/latest", None), - "pytest": ("https://docs.pytest.org/en/latest", None), - "python": ("https://docs.python.org/3", None), - "rich": ("https://rich.readthedocs.io/en/stable", None), -} - -# The default replacements for |version| and |release|, also used in various -# other places throughout the built documents. -# -# The short X.Y version. -version = VERSION -# The full version, including alpha/beta/rc tags. -release = VERSION - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -today_fmt = "%F" # ISO date format - -# List of documents that shouldn't be included in the build. -# unused_docs = [] - -# List of directories, relative to source directories, that shouldn't be -# searched for source files. -# exclude_dirs = [] - -# A list of glob-style patterns that should be excluded when looking -# for source files. -# OBSOLETE - removing this - dharmabumstead 2018-02-06 -exclude_patterns = ["README.md"] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -default_role = "any" - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "ansible" - -highlight_language = "YAML+Jinja" - -# Options for HTML output -# ----------------------- - -html_theme_path = ["../_themes"] -html_theme = "sphinx_ansible_theme" - -html_theme_options = { - "collapse_navigation": False, - "analytics_id": "UA-128382387-1", - # cspell:disable-next-line - "tag_manager_id": "GTM-5FGNF6S", - "style_nav_header_background": "#5bbdbf", - "style_external_links": True, - # 'canonical_url': "https://docs.ansible.com/ansible/latest/", - "vcs_pageview_mode": "edit", - "navigation_depth": 3, - "display_version": False, - "logo_only": True, -} - -html_context = { - "display_github": "True", - "github_user": "ansible", - "github_repo": "ansible-lint", - "github_version": "main/docs/", - "current_version": version, - "latest_version": "latest", - # list specifically out of order to make latest work - "available_versions": ("latest",), -} - -# This appears on the left side of the page, in the header bar -html_short_title = "Ansible Lint Documentation" - -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -# html_style = 'solar.css' - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -html_title = "Ansible Lint Documentation" - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (within the static path) to place at the top of -# the sidebar. -# -# ssbarnea: Do not put relative path because it will not load from some deeper -# pages as the relative path will be wrong, probably a bug in our schema. -html_logo = "_static/ansible-lint.svg" - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -# ssbarnea: Do not put SVG or PND here due to limited browser support. The -# value is relative to config file! -html_favicon = "_static/images/favicon.ico" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['.static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -html_last_updated_fmt = "%b %d, %Y" - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_use_modindex = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, the reST sources are included in the HTML build as _sources/. -html_copy_source = False - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -html_use_opensearch = "https://ansible-lint.readthedocs.io/" - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = '' - -autoclass_content = "both" - -# table width fix via: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html -html_static_path = ["_static"] - -html_css_files = [ # relative to html_static_path - "theme_overrides.css", # override wide tables in RTD theme - "ansi.css", -] - -linkcheck_workers = 25 - -# Matrix room links look like they have anchors -linkcheck_anchors_ignore = [ - "^!", - "^/#[a-z]+:ansible\\.com$", -] - -nitpicky = True -nitpick_ignore = [ - ("py:class", "AnsibleBaseYAMLObject"), - ("py:class", "ansible.module_utils.basic.AnsibleModule"), - ("py:class", "ansible.plugins.loader.PluginLoadContext"), - ("py:class", "BasePathLike"), - ("py:class", "CommentedMap"), - ("py:class", "CommentedSeq"), - ("py:class", "CompletedProcess"), - ("py:class", "FileType"), - ("py:class", "LintResult"), - ("py:class", "Lintable"), - ("py:class", "MatchError"), - ("py:class", "Namespace"), - ("py:class", "Path"), - ("py:class", "Pattern"), - ("py:class", "RulesCollection"), - ("py:class", "StreamType"), # used in Emitter's type annotation - ("py:class", "Templar"), - ("py:class", "_pytest.fixtures.SubRequest"), - ("py:class", "ansible.parsing.yaml.objects.AnsibleBaseYAMLObject"), - ("py:class", "ansible.template.Templar"), - ("py:class", "handlers"), - ("py:class", "meta"), - ("py:class", "playbook"), - ("py:class", "re.Pattern"), - ("py:class", "requirements"), - ("py:class", "role"), - ("py:class", "ruamel.yaml.comments.CommentedMap"), - ("py:class", "ruamel.yaml.comments.CommentedSeq"), - ("py:class", "ruamel.yaml.constructor.RoundTripConstructor"), - ("py:class", "ruamel.yaml.emitter.Emitter"), - ("py:class", "ruamel.yaml.emitter.ScalarAnalysis"), - ("py:class", "ruamel.yaml.main.YAML"), - ("py:class", "ruamel.yaml.nodes.ScalarNode"), - ("py:class", "ruamel.yaml.representer.RoundTripRepresenter"), - ("py:class", "ruamel.yaml.scalarint.ScalarInt"), - ("py:class", "ruamel.yaml.tokens.CommentToken"), - ("py:class", "tasks"), - ("py:class", "yaml"), - ("py:class", "yamllint.config.YamlLintConfig"), - ("py:obj", "Any"), - ("py:obj", "ansiblelint.formatters.T"), -] - -myst_heading_anchors = 3 -myst_ref_domains = ("std", "py") diff --git a/docs/configuring.md b/docs/configuring.md index 4976baed76..49deb3d4e3 100644 --- a/docs/configuring.md +++ b/docs/configuring.md @@ -1,29 +1,29 @@ -(configuring-ansible-lint)= - # Configuration -```{contents} Topics - -``` - Customize how Ansible-lint runs against automation content to suit your needs. -You can ignore certain rules, enable `opt-in` rules, and control various other settings. +You can ignore certain rules, enable `opt-in` rules, and control various other +settings. -Ansible-lint loads configuration from a file in the current working directory or from a file that you specify in the command line. -If you provide configuration on both via a config file and on the command line, list values are merged (for example `exclude_paths`) and **True** is preferred for boolean values like `quiet`. +Ansible-lint loads configuration from a file in the current working directory or +from a file that you specify in the command line. If you provide configuration +on both via a config file and on the command line, list values are merged (for +example `exclude_paths`) and **True** is preferred for boolean values like +`quiet`. ## Using local configuration files -Specify Ansible-lint configuration in either `.ansible-lint` or `.config/ansible-lint.yml` in your current working directory. +Specify Ansible-lint configuration in either `.ansible-lint` or +`.config/ansible-lint.yml` in your current working directory. -```{note} -If Ansible-lint cannot find a configuration file in the current directory it attempts to locate it in a parent directory. -However Ansible-lint does not try to load configuration that is outside the git repository. -``` +!!! note + + If Ansible-lint cannot find a configuration file in the current directory it attempts to locate it in a parent directory. + However Ansible-lint does not try to load configuration that is outside the git repository. ## Specifying configuration files -Use the `-c ` CLI flag with command line invocations of Ansible-lint, for example: +Use the `-c ` CLI flag with command line invocations of Ansible-lint, +for example: ```bash ansible-lint -c path/to/ansible-lint-dev.yml @@ -34,15 +34,17 @@ ansible-lint -c path/to/ansible-lint-dev.yml The following values are supported, and function identically to their CLI counterparts: -```{literalinclude} ../.ansible-lint -:language: yaml +```yaml +--8<-- ".ansible-lint" ``` ## Pre-commit setup -To use Ansible-lint with [pre-commit], add the following to the `.pre-commit-config.yaml` file in your local repository. +To use Ansible-lint with [pre-commit], add the following to the +`.pre-commit-config.yaml` file in your local repository. -Change **rev:** to either a commit sha or tag of Ansible-lint that contains `.pre-commit-hooks.yaml`. +Change **rev:** to either a commit sha or tag of Ansible-lint that contains +`.pre-commit-hooks.yaml`. ```yaml - repo: https://github.com/ansible/ansible-lint.git diff --git a/docs/contributing.md b/docs/contributing.md index 91e0091101..ebd19711c1 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,33 +1,94 @@ -```{include} ../.github/CONTRIBUTING.md - :end-before: DO-NOT-REMOVE-deps-snippet-PLACEHOLDER +# Contributing to Ansible-lint + +To contribute to ansible-lint, please use pull requests on a branch of your own +fork. + +After [creating your fork on GitHub], you can do: + +```shell-session +$ git clone git@github.com:your-name/ansible-lint +$ cd ansible-lint +$ git checkout -b your-branch-name +# DO SOME CODING HERE +$ git add your new files +$ git commit -v +$ git push origin your-branch-name ``` -# Module dependency graph +You will then be able to create a pull request from your commit. + +All fixes to core functionality (i.e. anything except docs or examples) should +be accompanied by tests that fail prior to your change and succeed afterwards. + +Feel free to raise issues in the repo if you feel unable to contribute a code +fix. + +## Standards + +ansible-lint is flake8 compliant with **max-line-length** set to 100. + +ansible-lint works only with supported Ansible versions at the time it was +released. + +Automated tests will be run against all PRs for flake8 compliance and Ansible +compatibility — to check before pushing commits, just use +[tox](https://tox.wiki/en/latest/). + +% DO-NOT-REMOVE-deps-snippet-PLACEHOLDER + +## Talk to us -Extra care should be taken when considering adding any dependency. Removing -most dependencies on Ansible internals is desired as these can change -without any warning. +Use Github [discussions] forum or for a live chat experience try +`#ansible-devtools` IRC channel on libera.chat or Matrix room +[#devtools:ansible.com](https://matrix.to/#/#devtools:ansible.com). -```{command-output} _PIP_USE_IMPORTLIB_METADATA=0 pipdeptree -p ansible-lint - :shell: +For the full list of Ansible IRC and Mailing list, please see the [Ansible +Communication] page. Release announcements will be made to the [Ansible +Announce] list. +Possible security bugs should be reported via email to +. + +## Code of Conduct + +As with all Ansible projects, we have a [Code of Conduct]. + +[.flake8]: https://github.com/ansible/ansible-lint/blob/main/.flake8 +[ansible announce]: https://groups.google.com/forum/#!forum/ansible-announce +[ansible communication]: + https://docs.ansible.com/ansible/latest/community/communication.html +[code of conduct]: + https://docs.ansible.com/ansible/latest/community/code_of_conduct.html +[creating your fork on github]: https://guides.github.com/activities/forking/ +[discussions]: https://github.com/ansible/ansible-lint/discussions +[supported ansible versions]: + https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle +[tox]: https://tox.readthedocs.io + +## Module dependency graph + +Extra care should be taken when considering adding any dependency. Removing most +dependencies on Ansible internals is desired as these can change without any +warning. + +```bash exec="1" source="console" +_PIP_USE_IMPORTLIB_METADATA=0 pipdeptree -p ansible-lint ``` -# Adding a new rule +## Adding a new rule Writing a new rule is as easy as adding a single new rule, one that combines **implementation, testing and documentation**. -One good example is [MetaTagValidRule] which can easily be copied in order -to create a new rule by following the steps below: +One good example is [MetaTagValidRule] which can easily be copied in order to +create a new rule by following the steps below: - Use a short but clear class name, which must match the filename -- Pick an unused `id`, the first number is used to determine rule section. - Look at [rules](rules.md) page and pick one that matches the best - your new rule and ee which one fits best. -- Include `experimental` tag. Any new rule must stay as - experimental for at least two weeks until this tag is removed in next major - release. +- Pick an unused `id`, the first number is used to determine rule section. Look + at [rules](rules/index.md) page and pick one that matches the best your new + rule and ee which one fits best. +- Include `experimental` tag. Any new rule must stay as experimental for at + least two weeks until this tag is removed in next major release. - Update all class level variables. - Implement linting methods needed by your rule, these are those starting with **match** prefix. Implement only those you need. For the moment you will need @@ -45,4 +106,17 @@ to create a new rule by following the steps below: - Build the docs using {command}`tox -e docs` and check that the new rule is displayed correctly in them. -[metatagvalidrule]: https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/rules/meta_no_tags.py +[metatagvalidrule]: + https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/rules/meta_no_tags.py + +## Documentation changes + +To build the docs, run `tox -e docs`. At the end of the build, you will see the +local location of your built docs. + +Building docs locally may not be identical to CI/CD builds. We recommend you to +create a draft PR and check the RTD PR preview page too. + +If you do not want to learn the reStructuredText format, you can also +[file an issue](https://github.com/ansible/ansible-lint/issues), and let us know +how we can improve our documentation. diff --git a/docs/custom-rules.md b/docs/custom-rules.md index b752b758b7..8c57d90c31 100644 --- a/docs/custom-rules.md +++ b/docs/custom-rules.md @@ -1,16 +1,15 @@ -(defining-custom-rules)= - # Custom linting rules Define and use your own sets of rules with Ansible-lint. ## Rule definitions -You define each custom rule in a unique Python class file. -Default rules are named _DeprecatedVariableRule.py_, etc. +You define each custom rule in a unique Python class file. Default rules are +named _DeprecatedVariableRule.py_, etc. -Each rule should have a short description as a Python docstring wrapped in triple quotes `"""` immediately after the class name. -The short description should be brief and meaningfully explain the purpose of the rule to users. +Each rule should have a short description as a Python docstring wrapped in +triple quotes `"""` immediately after the class name. The short description +should be brief and meaningfully explain the purpose of the rule to users. Each rule definition should have the following parts: @@ -24,8 +23,13 @@ Each rule definition should also invoke one of the following methods: - `match` takes a line and returns: - None or False if the line does not match the test. - - True or a custom message if the line does match the test. (This allows one rule to test multiple behaviors - see e.g. the _CommandsInsteadOfModulesRule_.) -- `matchtask` operates on a single task or handler, such that tasks get standardized to always contain a _module_ key and _module_arguments_ key. Other common task modifiers, such as _when_, _with_items_, etc., are also available as keys if present in the task. + - True or a custom message if the line does match the test. (This allows one + rule to test multiple behaviors - see e.g. the + _CommandsInsteadOfModulesRule_.) +- `matchtask` operates on a single task or handler, such that tasks get + standardized to always contain a _module_ key and _module_arguments_ key. + Other common task modifiers, such as _when_, _with_items_, etc., are also + available as keys if present in the task. The following is an example rule that uses the `match` method: @@ -75,10 +79,10 @@ class TaskHasTag(AnsibleLintRule): return False ``` -The task argument to `matchtask` contains a number of keys - the critical -one is _action_. The value of `task['action']` contains the module being used, -and the arguments passed, both as key-value pairs and a list of other arguments -(e.g. the command used with shell). +The task argument to `matchtask` contains a number of keys - the critical one is +_action_. The value of `task['action']` contains the module being used, and the +arguments passed, both as key-value pairs and a list of other arguments (e.g. +the command used with shell). In ansible-lint 2.0.0, `task['action']['args']` was renamed `task['action']['module_arguments']` to avoid a clash when a module actually @@ -86,13 +90,14 @@ takes args as a parameter key (e.g. ec2_tag) In ansible-lint 3.0.0 `task['action']['module']` was renamed `task['action']['__ansible_module__']` to avoid a clash when a module take -module as an argument. As a precaution, `task['action']['module_arguments']` -was renamed `task['action']['__ansible_arguments__']`. +module as an argument. As a precaution, `task['action']['module_arguments']` was +renamed `task['action']['__ansible_arguments__']`. ## Packaging custom rules -Ansible-lint automatically loads and enables custom rules in Python packages from the _custom_ subdirectory. -This subdirectory is part of the Ansible-lint installation directory, for example: +Ansible-lint automatically loads and enables custom rules in Python packages +from the _custom_ subdirectory. This subdirectory is part of the Ansible-lint +installation directory, for example: `/usr/lib/python3.8/site-packages/ansiblelint/rules/custom/` @@ -100,7 +105,8 @@ To automatically load custom rules, do the following: 1. Package your custom rules as a Python package with a descriptive name. -2. Configure the \[options\] section of the `setup.cfg` of your custom rules Python package as in the following example: +2. Configure the \[options\] section of the `setup.cfg` of your custom rules + Python package as in the following example: ```yaml [options] @@ -110,4 +116,5 @@ To automatically load custom rules, do the following: ansiblelint.rules.custom. = ``` -3. Install the Python package into `/custom//`. +3. Install the Python package into + `/custom//`. diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000000..ea4ebc153b Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000000..f3626b0ae4 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000000..ffe210b6d7 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/index.md b/docs/index.md index 18df0e3af7..a800ff0dee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,52 +1,28 @@ -(lint-documentation)= - # Ansible Lint Documentation ## About Ansible Lint Ansible Lint is a command-line tool for linting **playbooks, roles and -collections** aimed toward any Ansible users. Its main goal is to promote -proven practices, patterns and behaviors while avoiding common pitfalls that -can easily lead to bugs or make code harder to maintain. +collections** aimed toward any Ansible users. Its main goal is to promote proven +practices, patterns and behaviors while avoiding common pitfalls that can easily +lead to bugs or make code harder to maintain. Ansible lint is also supposed to help users upgrade their code to work with -newer versions of Ansible. Due to this reason we recommend using it with -the newest version of Ansible, even if the version used in production may be -older. +newer versions of Ansible. Due to this reason we recommend using it with the +newest version of Ansible, even if the version used in production may be older. As any other linter, it is opinionated. Still, its rules are the result of -community contributions and they can always be disabled based individually or -by category by each user. - -[Ansible Galaxy project](https://github.com/ansible/galaxy/) makes use of -this linter to compute quality scores for [Galaxy Hub](https://galaxy.ansible.com) -contributed content. This does not mean this tool only targets those -that want to share their code. Files like `galaxy.yml`, or sections like -`galaxy_info` inside `meta.yml` help with documentation and maintenance, -even for unpublished roles or collections. - -The project was originally started by [@willthames](https://github.com/willthames/) -and has since been adopted by the Ansible Community team. Its development is -purely community driven while keeping permanent communications with other -Ansible teams. - -```{toctree} -:caption: User Guide -:maxdepth: 1 - -Philosophy -installing -usage -configuring -using-profiles -rules -``` - -```{toctree} -:caption: Developer Guide -:maxdepth: 1 - -Contributing -custom-rules -Private API -``` +community contributions and they can always be disabled based individually or by +category by each user. + +[Ansible Galaxy project](https://github.com/ansible/galaxy/) makes use of this +linter to compute quality scores for [Galaxy Hub](https://galaxy.ansible.com) +contributed content. This does not mean this tool only targets those that want +to share their code. Files like `galaxy.yml`, or sections like `galaxy_info` +inside `meta.yml` help with documentation and maintenance, even for unpublished +roles or collections. + +The project was originally started by +[@willthames](https://github.com/willthames/) and has since been adopted by the +Ansible Community team. Its development is purely community driven while keeping +permanent communications with other Ansible teams. diff --git a/docs/installing.md b/docs/installing.md index b63731f9e8..026b580d68 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -1,38 +1,33 @@ -(installing-lint)= - # Installing -```{contents} Topics - -``` - Install Ansible-lint to apply rules and follow best practices with your automation content. -```{note} -Ansible-lint does not currently support installation on Windows systems. -``` +!!! note -```{warning} -Ansible-lint does not support any installation methods that are not -mentioned in this document. Before raising any bugs related to installation, -review all of the following details: - -- You should use installation methods outlined in this document only. -- You should upgrade the Python installer (`pip` or `pipx`) to the latest version - available from pypi.org. If you used a system package manager, you - will need to upgrade the installer to a newer version. -- If you are installing from a git zip archive, which is not supported but should work, - ensure you use the main branch and the latest version of pip and setuptools. -- If you are installing Ansible-lint within a container or system package, you - should not report the issue here. Contact the relevant container or package - provider instead. -- If you are using [poetry](https://python-poetry.org/), read this - [discussion](https://github.com/ansible/ansible-lint/discussions/2820#discussioncomment-4400380). - -Pull requests to improve installation instructions are welcome. Any new issues related to -installation will be closed and locked. -``` + Ansible-lint does not currently support installation on Windows systems. + +!!! warning + + Ansible-lint does not support any installation methods that are not mentioned in + this document. Before raising any bugs related to installation, review all of + the following details: + + - You should use installation methods outlined in this document only. + - You should upgrade the Python installer (`pip` or `pipx`) to the latest + version available from pypi.org. If you used a system package manager, you + will need to upgrade the installer to a newer version. + - If you are installing from a git zip archive, which is not supported but + should work, ensure you use the main branch and the latest version of pip and + setuptools. + - If you are installing Ansible-lint within a container or system package, you + should not report the issue here. Contact the relevant container or package + provider instead. + - If you are using [poetry](https://python-poetry.org/), read this + [discussion](https://github.com/ansible/ansible-lint/discussions/2820#discussioncomment-4400380). + + Pull requests to improve installation instructions are welcome. Any new issues + related to installation will be closed and locked. For a container image, we recommend using [creator-ee](https://github.com/ansible/creator-ee/), which includes @@ -52,7 +47,7 @@ current Python environment as an alternative to creating a virtual environment. ```bash # This also installs ansible-core if it is not already installed -pip3 install "ansible-lint" +pip3 install ansible-lint ``` ## Installing on Fedora and RHEL @@ -64,10 +59,10 @@ the `dnf` package manager. dnf install ansible-lint ``` -```{note} -On RHEL, `ansible-lint` package is part of "Red Hat Ansible Automation Platform" subscription, which needs -to be activated. -``` +!!! note + + On RHEL, `ansible-lint` package is part of "Red Hat Ansible Automation + Platform" subscription, which needs to be activated. ## Installing from source code diff --git a/docs/profiles.md b/docs/profiles.md new file mode 100644 index 0000000000..d105ddb136 --- /dev/null +++ b/docs/profiles.md @@ -0,0 +1,113 @@ + + +# Profiles + +Ansible-lint profiles gradually increase the strictness of rules as your Ansible +content lifecycle. To configure linter to use a specific profile, read +[applying-profiles][]. + +!!! note + + Rules with `*` in the suffix are not yet implemented but are documented with linked GitHub issues. + +## min + +The `min` profile ensures that Ansible can load content. Rules in this profile +are mandatory because they prevent fatal errors. You can add files to the +exclude list or provide dependencies to load the correct files. + +- [internal-error](rules/internal-error/) +- [load-failure](rules/load-failure/) +- [parser-error](rules/parser-error/) +- [syntax-check](rules/syntax-check/) + +## basic + +The `basic` profile prevents common coding issues and enforces standard styles +and formatting. It extends [min](#min) profile. + +- [command-instead-of-module](rules/command-instead-of-module/) +- [command-instead-of-shell](rules/command-instead-of-shell/) +- [deprecated-bare-vars](rules/deprecated-bare-vars/) +- [deprecated-command-syntax](rules/deprecated-command-syntax/) +- [deprecated-local-action](rules/deprecated-local-action/) +- [deprecated-module](rules/deprecated-module/) +- [inline-env-var](rules/inline-env-var/) +- [key-order](rules/key-order/) +- [literal-compare](rules/literal-compare/) +- [jinja](rules/jinja/) +- [no-jinja-when](rules/no-jinja-when/) +- [no-tabs](rules/no-tabs/) +- [partial-become](rules/partial-become/) +- [playbook-extension](rules/playbook-extension/) +- [role-name](rules/role-name/) +- [schema](rules/schema/) +- [name](rules/name/) +- [var-naming](rules/var-naming/) +- [yaml](rules/yaml/) + +## moderate + +The `moderate` profile ensures that content adheres to best practices for making +content easier to read and maintain. It extends [basic](#basic) profile. + +- [name[template]](rules/name/) +- [name[imperative]](https://github.com/ansible/ansible-lint/issues/2170) +- [name[casing]](rules/name/) +- [no-free-form](https://github.com/ansible/ansible-lint/issues/2117) +- [spell-var-name](https://github.com/ansible/ansible-lint/issues/2168) + +## safety + +The `safety` profile avoids module calls that can have non-determinant outcomes +or security concerns. It extends [moderate](#moderate) profile. + +- [avoid-implicit](rules/avoid-implicit/) +- [latest](rules/latest/) +- [package-latest](rules/package-latest/) +- [risky-file-permissions](rules/risky-file-permissions/) +- [risky-octal](rules/risky-octal/) +- [risky-shell-pipe](rules/risky-shell-pipe/) + +## shared + +The `shared` profile ensures that content follows best practices for packaging +and publishing. This profile is intended for content creators who want to make +Ansible playbooks, roles, or collections available from +[galaxy.ansible.com](https://galaxy.ansible.com), +[automation-hub](https://console.redhat.com/ansible/automation-hub), or a +private instance. It extends [safety](#safety) profile. + +- [galaxy](rules/galaxy/) +- [ignore-errors](rules/ignore-errors/) +- [layout](https://github.com/ansible/ansible-lint/issues/1900) +- [meta-incorrect](rules/meta-incorrect/) +- [meta-no-info](rules/meta-no-info/) +- [meta-no-tags](rules/meta-no-tags/) +- [meta-video-links](rules/meta-video-links/) +- [meta-version](https://github.com/ansible/ansible-lint/issues/2103) +- [meta-unsupported-ansible](https://github.com/ansible/ansible-lint/issues/2102) +- [no-changed-when](rules/no-changed-when/) +- [no-changelog](https://github.com/ansible/ansible-lint/issues/2101) +- [no-handler](rules/no-handler/) +- [no-relative-paths](rules/no-relative-paths/) +- [max-block-depth](https://github.com/ansible/ansible-lint/issues/2173) +- [max-tasks](https://github.com/ansible/ansible-lint/issues/2172) +- [unsafe-loop](https://github.com/ansible/ansible-lint/issues/2038) + +## production + +The `production` profile ensures that content meets requirements for inclusion +in +[Ansible Automation Platform (AAP)](https://www.redhat.com/en/technologies/management/ansible) +as validated or certified content. It extends [shared](#shared) profile. + +- [avoid-dot-notation](https://github.com/ansible/ansible-lint/issues/2174) +- [disallowed-ignore](https://github.com/ansible/ansible-lint/issues/2121) +- [fqcn](rules/fqcn/) +- [import-task-no-when](https://github.com/ansible/ansible-lint/issues/2219) +- [meta-no-dependencies](https://github.com/ansible/ansible-lint/issues/2159) +- [single-entry-point](https://github.com/ansible/ansible-lint/issues/2242) +- [use-loop](https://github.com/ansible/ansible-lint/issues/2204) diff --git a/docs/rules.md b/docs/rules.md deleted file mode 100644 index a0f942ec87..0000000000 --- a/docs/rules.md +++ /dev/null @@ -1,10 +0,0 @@ -(lint-rules)= - -# Rules - -```{toctree} -:maxdepth: 1 -:glob: - -rules/* -``` diff --git a/docs/rules/.gitignore b/docs/rules/.gitignore deleted file mode 100644 index 9393a70fdb..0000000000 --- a/docs/rules/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -# Generated files -*.md diff --git a/docs/rules/args.md b/docs/rules/args.md new file mode 120000 index 0000000000..194c2d3329 --- /dev/null +++ b/docs/rules/args.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/args.md \ No newline at end of file diff --git a/docs/rules/avoid-implicit.md b/docs/rules/avoid-implicit.md new file mode 120000 index 0000000000..4ddfc8237c --- /dev/null +++ b/docs/rules/avoid-implicit.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/avoid_implicit.md \ No newline at end of file diff --git a/docs/rules/command-instead-of-module.md b/docs/rules/command-instead-of-module.md new file mode 120000 index 0000000000..9f6809d903 --- /dev/null +++ b/docs/rules/command-instead-of-module.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/command_instead_of_module.md \ No newline at end of file diff --git a/docs/rules/command-instead-of-shell.md b/docs/rules/command-instead-of-shell.md new file mode 120000 index 0000000000..2bf0747ce0 --- /dev/null +++ b/docs/rules/command-instead-of-shell.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/command_instead_of_shell.md \ No newline at end of file diff --git a/docs/rules/deprecated-bare-vars.md b/docs/rules/deprecated-bare-vars.md new file mode 120000 index 0000000000..80ca8f7df9 --- /dev/null +++ b/docs/rules/deprecated-bare-vars.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_bare_vars.md \ No newline at end of file diff --git a/docs/rules/deprecated-command-syntax.md b/docs/rules/deprecated-command-syntax.md new file mode 120000 index 0000000000..70cb557401 --- /dev/null +++ b/docs/rules/deprecated-command-syntax.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_command_syntax.md \ No newline at end of file diff --git a/docs/rules/deprecated-local-action.md b/docs/rules/deprecated-local-action.md new file mode 120000 index 0000000000..fd44cd8d78 --- /dev/null +++ b/docs/rules/deprecated-local-action.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_local_action.md \ No newline at end of file diff --git a/docs/rules/deprecated-module.md b/docs/rules/deprecated-module.md new file mode 120000 index 0000000000..28dfe7fdbc --- /dev/null +++ b/docs/rules/deprecated-module.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/deprecated_module.md \ No newline at end of file diff --git a/docs/rules/empty-string-compare.md b/docs/rules/empty-string-compare.md new file mode 120000 index 0000000000..3470d52774 --- /dev/null +++ b/docs/rules/empty-string-compare.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/empty_string_compare.md \ No newline at end of file diff --git a/docs/rules/fqcn.md b/docs/rules/fqcn.md new file mode 120000 index 0000000000..5623faeaab --- /dev/null +++ b/docs/rules/fqcn.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/fqcn.md \ No newline at end of file diff --git a/docs/rules/galaxy.md b/docs/rules/galaxy.md new file mode 120000 index 0000000000..02cebd0eac --- /dev/null +++ b/docs/rules/galaxy.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/galaxy.md \ No newline at end of file diff --git a/docs/rules/ignore-errors.md b/docs/rules/ignore-errors.md new file mode 120000 index 0000000000..ea5578d78f --- /dev/null +++ b/docs/rules/ignore-errors.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/ignore_errors.md \ No newline at end of file diff --git a/docs/rules/index.md b/docs/rules/index.md new file mode 100644 index 0000000000..68851813a9 --- /dev/null +++ b/docs/rules/index.md @@ -0,0 +1,52 @@ +# Rules + +- [args][] +- [avoid-implicit][] +- [command-instead-of-module][] +- [command-instead-of-shell][] +- [deprecated-bare-vars][] +- [deprecated-command-syntax][] +- [deprecated-local-action][] +- [deprecated-module][] +- [empty-string-compare][] +- [fqcn][] +- [galaxy][] +- [ignore-errors][] +- [inline-env-var][] +- [internal-error][] +- [jinja][] +- [key-order][] +- [latest][] +- [literal-compare][] +- [load-failure][] +- [loop-var-prefix][] +- [meta-incorrect][] +- [meta-no-info][] +- [meta-no-tags][] +- [meta-unsupported-ansible][] +- [meta-video-links][] +- [name][] +- [no-changed-when][] +- [no-free-form][] +- [no-handler][] +- [no-jinja-when][] +- [no-log-password][] +- [no-prompting][] +- [no-relative-paths][] +- [no-same-owner][] +- [no-tabs][] +- [only-builtins][] +- [package-latest][] +- [parser-error][] +- [partial-become][] +- [playbook-extension][] +- [risky-file-permissions][] +- [risky-octal][] +- [risky-shell-pipe][] +- [role-name][] +- [run-once][] +- [schema][] +- [syntax-check][] +- [var-naming][] +- [warning][] +- [yaml][] diff --git a/docs/rules/inline-env-var.md b/docs/rules/inline-env-var.md new file mode 120000 index 0000000000..8942b5c24b --- /dev/null +++ b/docs/rules/inline-env-var.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/inline_env_var.md \ No newline at end of file diff --git a/docs/rules/internal-error.md b/docs/rules/internal-error.md new file mode 120000 index 0000000000..828768550b --- /dev/null +++ b/docs/rules/internal-error.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/internal_error.md \ No newline at end of file diff --git a/docs/rules/jinja.md b/docs/rules/jinja.md new file mode 120000 index 0000000000..6f5fc6e02a --- /dev/null +++ b/docs/rules/jinja.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/jinja.md \ No newline at end of file diff --git a/docs/rules/key-order.md b/docs/rules/key-order.md new file mode 120000 index 0000000000..929faa69ac --- /dev/null +++ b/docs/rules/key-order.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/key_order.md \ No newline at end of file diff --git a/docs/rules/latest.md b/docs/rules/latest.md new file mode 120000 index 0000000000..6280f1a808 --- /dev/null +++ b/docs/rules/latest.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/latest.md \ No newline at end of file diff --git a/docs/rules/literal-compare.md b/docs/rules/literal-compare.md new file mode 120000 index 0000000000..4a7ab236fb --- /dev/null +++ b/docs/rules/literal-compare.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/literal_compare.md \ No newline at end of file diff --git a/docs/rules/load-failure.md b/docs/rules/load-failure.md new file mode 120000 index 0000000000..38a66a68cb --- /dev/null +++ b/docs/rules/load-failure.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/load-failure.md \ No newline at end of file diff --git a/docs/rules/loop-var-prefix.md b/docs/rules/loop-var-prefix.md new file mode 120000 index 0000000000..6cebf6aced --- /dev/null +++ b/docs/rules/loop-var-prefix.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/loop_var_prefix.md \ No newline at end of file diff --git a/docs/rules/meta-incorrect.md b/docs/rules/meta-incorrect.md new file mode 120000 index 0000000000..34c18915ca --- /dev/null +++ b/docs/rules/meta-incorrect.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_incorrect.md \ No newline at end of file diff --git a/docs/rules/meta-no-info.md b/docs/rules/meta-no-info.md new file mode 120000 index 0000000000..1e9371577a --- /dev/null +++ b/docs/rules/meta-no-info.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_no_info.md \ No newline at end of file diff --git a/docs/rules/meta-no-tags.md b/docs/rules/meta-no-tags.md new file mode 120000 index 0000000000..b103c5706b --- /dev/null +++ b/docs/rules/meta-no-tags.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_no_tags.md \ No newline at end of file diff --git a/docs/rules/meta-unsupported-ansible.md b/docs/rules/meta-unsupported-ansible.md new file mode 120000 index 0000000000..8fcb1c74ef --- /dev/null +++ b/docs/rules/meta-unsupported-ansible.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_unsupported_ansible.md \ No newline at end of file diff --git a/docs/rules/meta-video-links.md b/docs/rules/meta-video-links.md new file mode 120000 index 0000000000..176559db40 --- /dev/null +++ b/docs/rules/meta-video-links.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/meta_video_links.md \ No newline at end of file diff --git a/docs/rules/name.md b/docs/rules/name.md new file mode 120000 index 0000000000..213f9244bb --- /dev/null +++ b/docs/rules/name.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/name.md \ No newline at end of file diff --git a/docs/rules/no-changed-when.md b/docs/rules/no-changed-when.md new file mode 120000 index 0000000000..e821c776bd --- /dev/null +++ b/docs/rules/no-changed-when.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_changed_when.md \ No newline at end of file diff --git a/docs/rules/no-free-form.md b/docs/rules/no-free-form.md new file mode 120000 index 0000000000..ee80943cf0 --- /dev/null +++ b/docs/rules/no-free-form.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_free_form.md \ No newline at end of file diff --git a/docs/rules/no-handler.md b/docs/rules/no-handler.md new file mode 120000 index 0000000000..1b690c6de5 --- /dev/null +++ b/docs/rules/no-handler.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_handler.md \ No newline at end of file diff --git a/docs/rules/no-jinja-when.md b/docs/rules/no-jinja-when.md new file mode 120000 index 0000000000..d2f945348f --- /dev/null +++ b/docs/rules/no-jinja-when.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_jinja_when.md \ No newline at end of file diff --git a/docs/rules/no-log-password.md b/docs/rules/no-log-password.md new file mode 120000 index 0000000000..ac5e8698a7 --- /dev/null +++ b/docs/rules/no-log-password.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_log_password.md \ No newline at end of file diff --git a/docs/rules/no-prompting.md b/docs/rules/no-prompting.md new file mode 120000 index 0000000000..49b3d4b906 --- /dev/null +++ b/docs/rules/no-prompting.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_prompting.md \ No newline at end of file diff --git a/docs/rules/no-relative-paths.md b/docs/rules/no-relative-paths.md new file mode 120000 index 0000000000..6fc7d42119 --- /dev/null +++ b/docs/rules/no-relative-paths.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_relative_paths.md \ No newline at end of file diff --git a/docs/rules/no-same-owner.md b/docs/rules/no-same-owner.md new file mode 120000 index 0000000000..6367a7ad58 --- /dev/null +++ b/docs/rules/no-same-owner.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_same_owner.md \ No newline at end of file diff --git a/docs/rules/no-tabs.md b/docs/rules/no-tabs.md new file mode 120000 index 0000000000..d938e62586 --- /dev/null +++ b/docs/rules/no-tabs.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/no_tabs.md \ No newline at end of file diff --git a/docs/rules/only-builtins.md b/docs/rules/only-builtins.md new file mode 120000 index 0000000000..7fa5e7aa6f --- /dev/null +++ b/docs/rules/only-builtins.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/only_builtins.md \ No newline at end of file diff --git a/docs/rules/package-latest.md b/docs/rules/package-latest.md new file mode 120000 index 0000000000..18d6723a63 --- /dev/null +++ b/docs/rules/package-latest.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/package_latest.md \ No newline at end of file diff --git a/docs/rules/parser-error.md b/docs/rules/parser-error.md new file mode 120000 index 0000000000..954422ff1c --- /dev/null +++ b/docs/rules/parser-error.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/parser-error.md \ No newline at end of file diff --git a/docs/rules/partial-become.md b/docs/rules/partial-become.md new file mode 120000 index 0000000000..f57aa23579 --- /dev/null +++ b/docs/rules/partial-become.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/partial_become.md \ No newline at end of file diff --git a/docs/rules/playbook-extension.md b/docs/rules/playbook-extension.md new file mode 120000 index 0000000000..429aa2fbb6 --- /dev/null +++ b/docs/rules/playbook-extension.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/playbook_extension.md \ No newline at end of file diff --git a/docs/rules/risky-file-permissions.md b/docs/rules/risky-file-permissions.md new file mode 120000 index 0000000000..a6718bf436 --- /dev/null +++ b/docs/rules/risky-file-permissions.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/risky_file_permissions.md \ No newline at end of file diff --git a/docs/rules/risky-octal.md b/docs/rules/risky-octal.md new file mode 120000 index 0000000000..dffaad5764 --- /dev/null +++ b/docs/rules/risky-octal.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/risky_octal.md \ No newline at end of file diff --git a/docs/rules/risky-shell-pipe.md b/docs/rules/risky-shell-pipe.md new file mode 120000 index 0000000000..444efa225c --- /dev/null +++ b/docs/rules/risky-shell-pipe.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/risky_shell_pipe.md \ No newline at end of file diff --git a/docs/rules/role-name.md b/docs/rules/role-name.md new file mode 120000 index 0000000000..e050ccdd2b --- /dev/null +++ b/docs/rules/role-name.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/role_name.md \ No newline at end of file diff --git a/docs/rules/run-once.md b/docs/rules/run-once.md new file mode 120000 index 0000000000..b238e258cd --- /dev/null +++ b/docs/rules/run-once.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/run_once.md \ No newline at end of file diff --git a/docs/rules/schema.md b/docs/rules/schema.md new file mode 120000 index 0000000000..a278289fcc --- /dev/null +++ b/docs/rules/schema.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/schema.md \ No newline at end of file diff --git a/docs/rules/syntax-check.md b/docs/rules/syntax-check.md new file mode 120000 index 0000000000..0e5e8f1e3a --- /dev/null +++ b/docs/rules/syntax-check.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/syntax_check.md \ No newline at end of file diff --git a/docs/rules/var-naming.md b/docs/rules/var-naming.md new file mode 120000 index 0000000000..50bc37b8be --- /dev/null +++ b/docs/rules/var-naming.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/var_naming.md \ No newline at end of file diff --git a/docs/rules/warning.md b/docs/rules/warning.md new file mode 120000 index 0000000000..9944a532ce --- /dev/null +++ b/docs/rules/warning.md @@ -0,0 +1 @@ +../../src/ansiblelint/_internal/warning.md \ No newline at end of file diff --git a/docs/rules/yaml.md b/docs/rules/yaml.md new file mode 120000 index 0000000000..b033a46114 --- /dev/null +++ b/docs/rules/yaml.md @@ -0,0 +1 @@ +../../src/ansiblelint/rules/yaml.md \ No newline at end of file diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000000..9b14d833eb --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,174 @@ +/* +Inspired by https://spec.draculatheme.com/ specification +*/ +:root { + --ansi-red: #ff5555; + --ansi-green: #50fa7b; + --ansi-blue: #265285; + --ansi-yellow: #ffb86c; /* Orange */ + --ansi-magenta: #bd93f9; /* Purple */ + --ansi-cyan: #8be9fd; + --ansi-black: #282a36; + --ansi-white: #f8f8f2; +} + +.-Color-Green, +.-Color-Faint-Green, +.-Color-Bold-Green { + color: var(--ansi-green); +} +.-Color-Red, +.-Color-Faint-Red, +.-Color-Bold-Red { + color: var(--ansi-red); +} +.-Color-Yellow, +.-Color-Faint-Yellow, +.-Color-Bold-Yellow { + color: var(--ansi-yellow); +} +.-Color-Blue, +.-Color-Faint-Blue, +.-Color-Bold-Blue { + color: var(--ansi-blue); +} +.-Color-Magenta, +.-Color-Faint-Magenta, +.-Color-Bold-Magenta { + color: var(--ansi-magenta); +} +.-Color-Cyan, +.-Color-Faint-Cyan, +.-Color-Bold-Cyan { + color: var(--ansi-cyan); +} +.-Color-White, +.-Color-Faint-White, +.-Color-Bold-White { + color: var(--ansi-white); +} +.-Color-Black, +.-Color-Faint-Black, +.-Color-Bold-Black { + color: var(--ansi-black); +} + +.-Color-Faint { + opacity: 0.5; +} + +.-Color-Bold { + font-weight: bold; +} + +.-Color-Black-BGBlack, +.-Color-BGBlack, +.-Color-Red-BGBlack, +.-Color-Green-BGBlack, +.-Color-Yellow-BGBlack, +.-Color-Blue-BGBlack, +.-Color-Magenta-BGBlack, +.-Color-Cyan-BGBlack, +.-Color-White-BGBlack { + background-color: var(--ansi-black); +} + +.-Color-Black-BGRed, +.-Color-BGRed, +.-Color-Red-BGRed, +.-Color-Green-BGRed, +.-Color-Yellow-BGRed, +.-Color-Blue-BGRed, +.-Color-Magenta-BGRed, +.-Color-Cyan-BGRed, +.-Color-White-BGRed { + background-color: var(--ansi-red); +} + +.-Color-Black-BGGreen, +.-Color-BGGreen, +.-Color-Red-BGGreen, +.-Color-Green-BGGreen, +.-Color-Yellow-BGGreen, +.-Color-Blue-BGGreen, +.-Color-Magenta-BGGreen, +.-Color-Cyan-BGGreen, +.-Color-White-BGGreen { + background-color: var(--ansi-green); +} + +.-Color-Black-BGYellow, +.-Color-BGYellow, +.-Color-Red-BGYellow, +.-Color-Green-BGYellow, +.-Color-Yellow-BGYellow, +.-Color-Blue-BGYellow, +.-Color-Magenta-BGYellow, +.-Color-Cyan-BGYellow, +.-Color-White-BGYellow { + background-color: var(--ansi-yellow); +} + +.-Color-Black-BGBlue, +.-Color-BGBlue, +.-Color-Red-BGBlue, +.-Color-Green-BGBlue, +.-Color-Yellow-BGBlue, +.-Color-Blue-BGBlue, +.-Color-Magenta-BGBlue, +.-Color-Cyan-BGBlue, +.-Color-White-BGBlue { + background-color: var(--ansi-blue); +} + +.-Color-Black-BGMagenta, +.-Color-BGMagenta, +.-Color-Red-BGMagenta, +.-Color-Green-BGMagenta, +.-Color-Yellow-BGMagenta, +.-Color-Blue-BGMagenta, +.-Color-Magenta-BGMagenta, +.-Color-Cyan-BGMagenta, +.-Color-White-BGMagenta { + background-color: var(--ansi-magenta); +} + +.-Color-Black-BGCyan, +.-Color-BGCyan, +.-Color-Red-BGCyan, +.-Color-Green-BGCyan, +.-Color-Yellow-BGCyan, +.-Color-Blue-BGCyan, +.-Color-Magenta-BGCyan, +.-Color-Cyan-BGCyan, +.-Color-White-BGCyan { + background-color: var(--ansi-cyan); +} + +.-Color-Black-BGWhite, +.-Color-BGWhite, +.-Color-Red-BGWhite, +.-Color-Green-BGWhite, +.-Color-Yellow-BGWhite, +.-Color-Blue-BGWhite, +.-Color-Magenta-BGWhite, +.-Color-Cyan-BGWhite, +.-Color-White-BGWhite { + background-color: var(--ansi-white); +} + +.-Color-Black-BGBlack, +.-Color-Red-BGRed, +.-Color-Blue-BGBlue { + text-shadow: 0 0 1px var(--ansi-white); +} + +.-Color-Green-BGGreen, +.-Color-Yellow-BGYellow, +.-Color-Cyan-BGCyan, +.-Color-White-BGWhite, +.-Color-Magenta-BGMagenta, +.-Color-Cyan-BGGreen, +.-Color-Green-BGCyan { + text-shadow: 0 0 1px var(--ansi-black); +} diff --git a/docs/usage.md b/docs/usage.md index f3cd1f065a..14f4a9ebe2 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,18 +1,12 @@ -(using-lint)= - # Using -```{contents} Topics - -``` - ## Using commands -After you install Ansible-lint, run `ansible-lint --help` to display available commands and their options. +After you install Ansible-lint, run `ansible-lint --help` to display available +commands and their options. -```{command-output} ansible-lint --help - :cwd: .. - :returncode: 0 +```bash exec="1" source="console" +ansible-lint --help ``` ### Command output @@ -22,108 +16,123 @@ Ansible-lint prints output on both `stdout` and `stderr`. - `stdout` displays rule violations. - `stderr` displays logging and free-form messages like statistics. -Most `ansible-lint` examples use pep8 as the output format (`-p`) which is machine parseable. +Most `ansible-lint` examples use pep8 as the output format (`-p`) which is +machine parseable. -Ansible-lint also print errors using their [annotation] format when it detects the `GITHUB_ACTIONS=true` and `GITHUB_WORKFLOW=...` variables. +Ansible-lint also print errors using their [annotation] format when it detects +the `GITHUB_ACTIONS=true` and `GITHUB_WORKFLOW=...` variables. -[annotation]: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message +[annotation]: + https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message ## Caching -For optimal performance, Ansible-lint creates caches with installed or mocked roles, collections, and modules in the `{project_dir}/.cache` folder. -The location of `{project_dir}` is passed with a command line argument, determined by the location of the configuration file, git project top-level directory, or user home directory. +For optimal performance, Ansible-lint creates caches with installed or mocked +roles, collections, and modules in the `{project_dir}/.cache` folder. The +location of `{project_dir}` is passed with a command line argument, determined +by the location of the configuration file, git project top-level directory, or +user home directory. To perform faster re-runs, Ansible-lint does not automatically clean the cache. If required you can do this manually by simply deleting the `.cache` folder. Ansible-lint creates a new cache on the next invocation. -You should add the `.cache` folder to the `.gitignore` file in your git repositories. +You should add the `.cache` folder to the `.gitignore` file in your git +repositories. ## Using progressive mode -For easier adoption, Ansible-lint can alert for rule violations that occur since the last commit. -This allows new code to be merged without any rule violations while allowing content developers to address historical violations at a different pace. +For easier adoption, Ansible-lint can alert for rule violations that occur since +the last commit. This allows new code to be merged without any rule violations +while allowing content developers to address historical violations at a +different pace. -The `--progressive` option runs Ansible-lint twice if rule violations exist in your content. -The second run is performed against a temporary git working copy that contains -the last commit. -Rule violations that exist in the last commit are ignored and Ansible-lint displays only the violations that exist in the new commit. +The `--progressive` option runs Ansible-lint twice if rule violations exist in +your content. The second run is performed against a temporary git working copy +that contains the last commit. Rule violations that exist in the last commit are +ignored and Ansible-lint displays only the violations that exist in the new +commit. ## Linting playbooks and roles -Ansible-lint recommends following the {ref}`collection structure layout ` whether you plan to build a collection or not. +Ansible-lint recommends following the +{ref}`collection structure layout ` whether you plan to +build a collection or not. -Following that layout assures the best integration with all ecosystem tools because it helps those tools better distinguish between random YAML files and files managed by Ansible. -When you call `ansible-lint` without arguments, it uses internal heuristics to determine file types. +Following that layout assures the best integration with all ecosystem tools +because it helps those tools better distinguish between random YAML files and +files managed by Ansible. When you call `ansible-lint` without arguments, it +uses internal heuristics to determine file types. -You can specify the list of **roles** or **playbooks** that you want to lint with the `-p` argument. -For example, to lint `examples/playbooks/play.yml` and `examples/roles/bobbins`, use the following command: +You can specify the list of **roles** or **playbooks** that you want to lint +with the `-p` argument. For example, to lint `examples/playbooks/play.yml` and +`examples/roles/bobbins`, use the following command: -```{command-output} ansible-lint --offline -p examples/playbooks/play.yml examples/roles/bobbins - :cwd: .. - :returncode: 2 - :nostderr: true +```bash exec="1" source="console" +ansible-lint --offline -p examples/playbooks/play.yml examples/roles/bobbins || true ``` ## Running example playbooks -Ansible-lint includes an `ansible-lint/examples` folder that contains example playbooks with different rule violations and undesirable characteristics. -You can run `ansible-lint` on the example playbooks to observe Ansible-lint in action, as follows: +Ansible-lint includes an `ansible-lint/examples` folder that contains example +playbooks with different rule violations and undesirable characteristics. You +can run `ansible-lint` on the example playbooks to observe Ansible-lint in +action, as follows: -```{command-output} ansible-lint --offline -p examples/playbooks/example.yml - :cwd: .. - :returncode: 2 - :nostderr: true +```bash exec="1" source="console" +ansible-lint --offline -p examples/playbooks/example.yml >/dev/null || true ``` -Ansible-lint also handles playbooks that include other playbooks, tasks, handlers, or roles, as the `examples/playbooks/include.yml` example demonstrates. +Ansible-lint also handles playbooks that include other playbooks, tasks, +handlers, or roles, as the `examples/playbooks/include.yml` example +demonstrates. -```{command-output} ansible-lint --offline --force-color --offline -p examples/playbooks/include.yml - :cwd: .. - :returncode: 2 - :nostderr: true +```bash exec="1" source="console" +ansible-lint --offline -p examples/playbooks/include.yml 2>/dev/null || true ``` -You can generate `JSON` reports based on the code-climate specification as the `examples/playbooks/norole.yml` example demonstrates. +You can generate `JSON` reports based on the code-climate specification as the +`examples/playbooks/norole.yml` example demonstrates. -```{command-output} ansible-lint --offline -f json examples/playbooks/norole.yml - :cwd: .. - :returncode: 2 - :nostderr: true +```bash exec="1" source="tabbed-left" result="json" +ansible-lint --offline -f json examples/playbooks/norole.yml 2>/dev/null || true ``` ## Specifying rules at runtime -By default, `ansible-lint` applies rules found in `ansible-lint/src/ansiblelint/rules`. -Use the `-r /path/to/custom-rules` option to specify the directory path to a set of custom rules. -For multiple custom rule sets, pass each set with a separate `-r` option. +By default, `ansible-lint` applies rules found in +`ansible-lint/src/ansiblelint/rules`. Use the `-r /path/to/custom-rules` option +to specify the directory path to a set of custom rules. For multiple custom rule +sets, pass each set with a separate `-r` option. -You can also combine the default rules with custom rules with the `-R` option along with one or more `-r` options. +You can also combine the default rules with custom rules with the `-R` option +along with one or more `-r` options. ### Including rules with tags -Each rule has an associated set of one or more tags. -Use the `-T` option to view the list of tags for each available rule. +Each rule has an associated set of one or more tags. Use the `-T` option to view +the list of tags for each available rule. -You can then use the `-t` option to specify a tag and include the associated rules in the lint run. -For example, the following `ansible-lint` command applies only the rules associated with the _idempotency_ tag: +You can then use the `-t` option to specify a tag and include the associated +rules in the lint run. For example, the following `ansible-lint` command applies +only the rules associated with the _idempotency_ tag: -```bash -$ ansible-lint -t idempotency playbook.yml +```bash exec="1" source="console" +ansible-lint -t idempotency playbook.yml ``` -The following shows the available tags in an example set of rules and the rules associated with each tag: +The following shows the available tags in an example set of rules and the rules +associated with each tag: -```{command-output} ansible-lint -T - :cwd: .. - :returncode: 0 - :nostderr: true +```bash exec="1" source="console" +ansible-lint -T 2>/dev/null ``` ### Excluding rules with tags -To exclude rules by identifiers or tags, use the `-x SKIP_LIST` option. -For example, the following command applies all rules except those with the _formatting_ and _metadata_ tags: +To exclude rules by identifiers or tags, use the `-x SKIP_LIST` option. For +example, the following command applies all rules except those with the +_formatting_ and _metadata_ tags: ```bash $ ansible-lint -x formatting,metadata playbook.yml @@ -131,27 +140,31 @@ $ ansible-lint -x formatting,metadata playbook.yml ### Ignoring rules -To only warn about rules, use the `-w WARN_LIST` option. -For example, the following command displays only warns about violations with rules associated with the `experimental` tag: +To only warn about rules, use the `-w WARN_LIST` option. For example, the +following command displays only warns about violations with rules associated +with the `experimental` tag: ```console $ ansible-lint -w experimental playbook.yml ``` -By default, the `WARN_LIST` includes the `['experimental']` tag. -If you define a custom `WARN_LIST` you must add `'experimental'` so that Ansible-lint does not fail against experimental rules. +By default, the `WARN_LIST` includes the `['experimental']` tag. If you define a +custom `WARN_LIST` you must add `'experimental'` so that Ansible-lint does not +fail against experimental rules. ## Muting warnings to avoid false positives -Not all linting rules are precise, some are general rules of thumb. -Advanced _git_, _yum_ or _apt_ usage, for example, can be difficult to achieve in a playbook. -In cases like this, Ansible-lint can incorrectly trigger rule violations. +Not all linting rules are precise, some are general rules of thumb. Advanced +_git_, _yum_ or _apt_ usage, for example, can be difficult to achieve in a +playbook. In cases like this, Ansible-lint can incorrectly trigger rule +violations. -To disable rule violations for specific tasks, and mute false positives, add `# noqa [rule_id]` to the end of the line. -It is best practice to add a comment that explains why rules are disabled. +To disable rule violations for specific tasks, and mute false positives, add +`# noqa [rule_id]` to the end of the line. It is best practice to add a comment +that explains why rules are disabled. -You can add the `# noqa [rule_id]` comment to the end of any line in a task. -You can also skip multiple rules with a space-separated list. +You can add the `# noqa [rule_id]` comment to the end of any line in a task. You +can also skip multiple rules with a space-separated list. ```yaml - name: This task would typically fire git-latest and partial-become rules @@ -168,10 +181,13 @@ If the rule is line-based, `# noqa [rule_id]` must be at the end of the line. dest: "{{dest_proj_path}}/foo.conf" # noqa jinja[spacing] ``` -If you want Ansible-lint to skip a rule entirely, use the `-x` command line argument or add it to `skip_list` in your configuration. +If you want Ansible-lint to skip a rule entirely, use the `-x` command line +argument or add it to `skip_list` in your configuration. -The least preferred method of skipping rules is to skip all task-based rules for a task, which does not skip line-based rules. -You can use the `skip_ansible_lint` tag with all tasks or the `warn` parameter with the _command_ or _shell_ modules, for example: +The least preferred method of skipping rules is to skip all task-based rules for +a task, which does not skip line-based rules. You can use the +`skip_ansible_lint` tag with all tasks or the `warn` parameter with the +_command_ or _shell_ modules, for example: ```yaml - name: This would typically fire deprecated-command-syntax @@ -187,3 +203,47 @@ You can use the `skip_ansible_lint` tag with all tasks or the `warn` parameter w tags: - skip_ansible_lint ``` + +## Applying profiles + +Ansible-lint profiles allow content creators to progressively improve the +quality of Ansible playbooks, roles, and collections. + +During early development cycles, you need Ansible-lint rules to be less strict. +Starting with the minimal profile ensures that Ansible can load your content. As +you move to the next stage of developing content, you can gradually apply +profiles to avoid common pitfalls and brittle complexity. Then, when you are +ready to publish or share your content, you can use the `shared` and +`production` profiles with much stricter rules. These profiles harden security, +guarantee reliability, and ensure your Ansible content is easy for others to +contribute to and use. + +!!! note + + Tags such as `opt-in` and `experimental` do not take effect for rules that are included in profiles, directly or indirectly. + If a rule is in a profile, Ansible-lint applies that rule to the content. + +After you install and configure `ansible-lint`, you can apply profiles as +follows: + +1. View available profiles with the `--list-profiles` flag. + + ```bash + ansible-lint --list-profiles + ``` + +2. Specify a profile with the `--profile` parameter to lint your content with + those rules, for example: + +- Enforce standard styles and formatting with the `basic` profile. + + ```bash + ansible-lint --profile=basic + ``` + +- Ensure automation consistency, reliability, and security with the `safety` + profile. + + ```bash + ansible-lint --profile=safety + ``` diff --git a/docs/using-profiles.md b/docs/using-profiles.md deleted file mode 100644 index 396cae5b34..0000000000 --- a/docs/using-profiles.md +++ /dev/null @@ -1,44 +0,0 @@ -(using-lint-profiles)= - -# Applying profiles - -Ansible-lint profiles allow content creators to progressively improve the quality of Ansible playbooks, roles, and collections. - -During early development cycles, you need Ansible-lint rules to be less strict. -Starting with the minimal profile ensures that Ansible can load your content. -As you move to the next stage of developing content, you can gradually apply profiles to avoid common pitfalls and brittle complexity. -Then, when you are ready to publish or share your content, you can use the `shared` and `production` profiles with much stricter rules. -These profiles harden security, guarantee reliability, and ensure your Ansible content is easy for others to contribute to and use. - -```{note} -Tags such as `opt-in` and `experimental` do not take effect for rules that are included in profiles, directly or indirectly. -If a rule is in a profile, Ansible-lint applies that rule to the content. -``` - -After you install and configure `ansible-lint`, you can apply profiles as follows: - -1. View available profiles with the `--list-profiles` flag. - - ```bash - ansible-lint --list-profiles - ``` - -2. Specify a profile with the `--profile` parameter to lint your content with those rules, for example: - -- Enforce standard styles and formatting with the `basic` profile. - - ```bash - ansible-lint --profile=basic - ``` - -- Ensure automation consistency, reliability, and security with the `safety` profile. - - ```bash - ansible-lint --profile=safety - ``` - -```{toctree} -:maxdepth: 1 - -profiles -``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..d8a99ee56b --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,195 @@ +--- +site_name: Ansible List Documentation +site_url: https://ansible-lint.readthedocs.io/ +repo_url: https://github.com/ansible/ansible-lint +edit_uri: blob/main/docs/ +copyright: Copyright © 2023 Red Hat, Inc. +docs_dir: docs +strict: true + +extra_css: + - stylesheets/extra.css + +theme: + name: "material" + logo: images/logo.svg + favicon: images/favicon.ico + features: + - content.code.copy + - content.action.edit + - navigation.expand + - navigation.sections + - navigation.instant + - navigation.indexes + - navigation.tracking + - toc.integrate + palette: + - media: "(prefers-color-scheme: light)" + primary: teal + accent: blue + scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode +extra: + social: + - icon: fontawesome/brands/python + link: https://pypi.org/project/ansible-lint/ + name: PyPI + - icon: fontawesome/solid/scroll + link: https://github.com/ansible/ansible-lint/releases + name: Releases + - icon: simple/mastodon + link: https://fosstodon.org/@ansible + name: Mastodon + - icon: fontawesome/brands/twitter + link: https://twitter.com/ansible + name: Twitter + - icon: simple/matrix + link: https://matrix.to/#/#devtools:ansible.com + name: Matrix + - icon: fontawesome/solid/comments + link: https://github.com/ansible/ansible-lint/discussions + name: Discussions + - icon: fontawesome/brands/github-alt + link: https://github.com/ansible/ansible-lint + name: GitHub + +nav: + - User Guide: + - home: index.md + - philosophy.md + - installing.md + - usage.md + - configuring.md + - profiles.md + - Rules: + - index: rules/index.md + - rules/args.md + - rules/avoid-implicit.md + - rules/command-instead-of-module.md + - rules/command-instead-of-shell.md + - rules/deprecated-bare-vars.md + - rules/deprecated-command-syntax.md + - rules/deprecated-local-action.md + - rules/deprecated-module.md + - rules/empty-string-compare.md + - rules/fqcn.md + - rules/galaxy.md + - rules/ignore-errors.md + - rules/inline-env-var.md + - rules/internal-error.md + - rules/jinja.md + - rules/key-order.md + - rules/latest.md + - rules/literal-compare.md + - rules/load-failure.md + - rules/loop-var-prefix.md + - rules/meta-incorrect.md + - rules/meta-no-info.md + - rules/meta-no-tags.md + - rules/meta-unsupported-ansible.md + - rules/meta-video-links.md + - rules/name.md + - rules/no-changed-when.md + - rules/no-free-form.md + - rules/no-handler.md + - rules/no-jinja-when.md + - rules/no-log-password.md + - rules/no-prompting.md + - rules/no-relative-paths.md + - rules/no-same-owner.md + - rules/no-tabs.md + - rules/only-builtins.md + - rules/package-latest.md + - rules/parser-error.md + - rules/partial-become.md + - rules/playbook-extension.md + - rules/risky-file-permissions.md + - rules/risky-octal.md + - rules/risky-shell-pipe.md + - rules/role-name.md + - rules/run-once.md + - rules/schema.md + - rules/syntax-check.md + - rules/var-naming.md + - rules/warning.md + - rules/yaml.md + - Developer Guide: + - Contributing: contributing.md + - custom-rules.md + +# - installation.md +# - using: +# - getting-started.md +# - usage.md +# - configuration.md +# - examples.md +# - faq.md +# - contributing.md +# - tags.md +# # - subprocess-tee: '!import https://github.com/pycontribs/subprocess-tee?branch=main&multi_docs=False' +# # - xxx: '!import https://github.com/eclipse-opensmartclide/smartclide-docs' + +plugins: + - autorefs + - markdown-exec + - gen-files: + scripts: + - src/ansiblelint/generate_docs.py + - search + - social + - tags + - mkdocstrings: + handlers: + python: + paths: [src] + options: + # Sphinx is for historical reasons, but we could consider switching if needed + # https://mkdocstrings.github.io/griffe/docstrings/ + docstring_style: sphinx + merge_init_into_class: yes + show_submodules: yes + import: + - url: https://docs.ansible.com/ansible/latest/objects.inv + domains: [py, std] + +markdown_extensions: + - admonition + - def_list + - footnotes + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets: + check_paths: true + - pymdownx.superfences + - pymdownx.magiclink: + repo_url_shortener: true + repo_url_shorthand: true + social_url_shorthand: true + social_url_shortener: true + user: facelessuser + repo: pymdown-extensions + normalize_issue_symbols: true + - pymdownx.tabbed: + alternate_style: true + - toc: + toc_depth: 2 + permalink: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - name: python + class: python + validator: !!python/name:markdown_exec.validator + format: !!python/name:markdown_exec.formatter diff --git a/pyproject.toml b/pyproject.toml index a70bf1f009..81080f5553 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,7 +85,7 @@ show_missing = true profile = "black" # add_imports = "from __future__ import annotations" known_first_party = "ansiblelint" -known_third_party = "ansible,pytest,ruamel,setuptools,sphinx,yaml" +known_third_party = "ansible,pytest,ruamel,setuptools,yaml" # https://black.readthedocs.io/en/stable/the_black_code_style.html#line-length multi_line_output = 3 include_trailing_comma = true diff --git a/src/ansiblelint/_internal/load-failure.md b/src/ansiblelint/_internal/load-failure.md new file mode 100644 index 0000000000..78daa0dcd5 --- /dev/null +++ b/src/ansiblelint/_internal/load-failure.md @@ -0,0 +1,12 @@ +# load-failure + +"Linter failed to process a file, possible invalid file. Possible reasons: + +* contains unsupported encoding (only UTF-8 is supported) +* not an Ansible file +* it contains some unsupported custom YAML objects (`!!` prefix) +* it was not able to decrypt an inline `!vault` block. + +This violation **is not** skippable, so it cannot be added to the `warn_list` +or the `skip_list`. If a vault decryption issue cannot be avoided, the +offending file can be added to `exclude_paths` configuration. diff --git a/src/ansiblelint/_internal/parser-error.md b/src/ansiblelint/_internal/parser-error.md new file mode 100644 index 0000000000..f6c7649286 --- /dev/null +++ b/src/ansiblelint/_internal/parser-error.md @@ -0,0 +1,5 @@ +# parser-error + +**AnsibleParserError.** + +Ansible parser fails; this usually indicates an invalid file. diff --git a/src/ansiblelint/generate_docs.py b/src/ansiblelint/generate_docs.py index 132e33c437..a52e125c69 100644 --- a/src/ansiblelint/generate_docs.py +++ b/src/ansiblelint/generate_docs.py @@ -64,6 +64,7 @@ def rules_as_docs(rules: RulesCollection) -> str: description += f" [more]({rule.link})" result += f"# {title}\n\n**{rule.shortdesc}**\n\n{description}" + result = result.strip() + "\n" f.write(result) return "All markdown files for rules were dumped!" @@ -134,9 +135,9 @@ def profiles_as_md(header: bool = False, docs_url: str = RULE_DOC_URL) -> str: Ansible-lint profiles gradually increase the strictness of rules as your Ansible content lifecycle. -```{note} -Rules with `*` in the suffix are not yet implemented but are documented with linked GitHub issues. -``` +!!! note + + Rules with `*` in the suffix are not yet implemented but are documented with linked GitHub issues. """ diff --git a/src/ansiblelint/rules/fqcn.md b/src/ansiblelint/rules/fqcn.md index 68358b35d3..fc96ed227b 100644 --- a/src/ansiblelint/rules/fqcn.md +++ b/src/ansiblelint/rules/fqcn.md @@ -3,40 +3,43 @@ This rule checks for fully-qualified collection names (FQCN) in Ansible content. Declaring an FQCN ensures that an action uses code from the correct namespace. -This avoids ambiguity and conflicts that can cause operations to fail or produce unexpected results. +This avoids ambiguity and conflicts that can cause operations to fail or produce +unexpected results. The `fqcn` rule has the following checks: - `fqcn[action]` - Use FQCN for module actions, such ... -- `fqcn[action-core]` - Checks for FQCNs from the `ansible.legacy` or `ansible.builtin` collection. +- `fqcn[action-core]` - Checks for FQCNs from the `ansible.legacy` or + `ansible.builtin` collection. - `fqcn[canonical]` - You should use canonical module name ... instead of ... -- `fqcn[keyword]` - Avoid `collections` keyword by using FQCN for all plugins, modules, roles and playbooks. +- `fqcn[keyword]` - Avoid `collections` keyword by using FQCN for all plugins, + modules, roles and playbooks. -```{note} -In most cases you should declare the `ansible.builtin` collection for internal Ansible actions. -You should declare the `ansible.legacy` collection if you use local overrides with actions, such with as the ``shell`` module. -``` +!!! note -```{warning} -This rule does not take [`collections` keyword](https://docs.ansible.com/ansible/latest/collections_guide/collections_using_playbooks.html#simplifying-module-names-with-the-collections-keyword) into consideration for resolving content. -The `collections` keyword provided a temporary mechanism transitioning to Ansible 2.9. -You should rewrite any content that uses the `collections:` key and avoid it where possible. -``` + In most cases you should declare the `ansible.builtin` collection for internal Ansible actions. + You should declare the `ansible.legacy` collection if you use local overrides with actions, such with as the ``shell`` module. + +!!! warning + + This rule does not take [`collections` keyword](https://docs.ansible.com/ansible/latest/collections_guide/collections_using_playbooks.html#simplifying-module-names-with-the-collections-keyword) into consideration for resolving content. + The `collections` keyword provided a temporary mechanism transitioning to Ansible 2.9. + You should rewrite any content that uses the `collections:` key and avoid it where possible. ## Canonical module names -Canonical module names are also known as **resolved module names** and they -are to be preferred for most cases. Many Ansible modules have multiple aliases -and redirects, as these were created over time while the content was refactored. +Canonical module names are also known as **resolved module names** and they are +to be preferred for most cases. Many Ansible modules have multiple aliases and +redirects, as these were created over time while the content was refactored. Still, all of them do finally resolve to the same module name, but not without adding some performance overhead. As very old aliases are at some point removed, it makes to just refresh the content to make it point to the current canonical name. -The only exception for using a canonical name is if your code still needs to -be compatible with a very old version of Ansible, one that does not know how -to resolve that name. If you find yourself in such a situation, feel free to -add this rule to the ignored list. +The only exception for using a canonical name is if your code still needs to be +compatible with a very old version of Ansible, one that does not know how to +resolve that name. If you find yourself in such a situation, feel free to add +this rule to the ignored list. ## Problematic Code @@ -58,7 +61,8 @@ add this rule to the ignored list. tasks: - name: Create an SSH connection # Use the FQCN for the legacy shell module and allow local overrides. - ansible.legacy.shell: ssh ssh_user@{{ ansible_ssh_host }} -o IdentityFile=path/to/my_rsa + ansible.legacy.shell: + ssh ssh_user@{{ ansible_ssh_host }} -o IdentityFile=path/to/my_rsa ``` ```yaml diff --git a/src/ansiblelint/rules/name.md b/src/ansiblelint/rules/name.md index 608ce67687..9df4213415 100644 --- a/src/ansiblelint/rules/name.md +++ b/src/ansiblelint/rules/name.md @@ -6,40 +6,38 @@ This is important because these names are the primary way to **identify** and This rule can produce messages as: -- `name[casing]` - All names should start with an uppercase letter for - languages that support it. +- `name[casing]` - All names should start with an uppercase letter for languages + that support it. - `name[missing]` - All tasks should be named. - `name[play]` - All plays should be named. - `name[prefix]` - Prefix task names in sub-tasks files. (opt-in) - `name[template]` - Jinja templates should only be at the end of 'name'. This helps with the identification of tasks inside the source code when they fail. - The use of templating inside `name` keys is discouraged as there - are multiple cases where the rendering of the name template is not possible. + The use of templating inside `name` keys is discouraged as there are multiple + cases where the rendering of the name template is not possible. -If you want to ignore some of the messages above, you can add any of them to -the `skip_list`. +If you want to ignore some of the messages above, you can add any of them to the +`skip_list`. ## name[prefix] -This rule applies only to included task files that are not named -`main.yml`. It suggests adding the stem of the file as a prefix to the task -name. +This rule applies only to included task files that are not named `main.yml`. It +suggests adding the stem of the file as a prefix to the task name. For example, if you have a task named `Restart server` inside a file named -`tasks/deploy.yml`, this rule suggests renaming it to -`deploy | Restart server`, so it would be easier to identify where it comes -from. +`tasks/deploy.yml`, this rule suggests renaming it to `deploy | Restart server`, +so it would be easier to identify where it comes from. For the moment, this sub-rule is just an **opt-in**, so you need to add it to your `enable_list` to activate it. -```{note} -This rule was designed by [Red Hat Community of Practice](https://redhat-cop.github.io/automation-good-practices/#_prefix_task_names_in_sub_tasks_files_of_roles). The reasoning behind it being -that in a complex roles or playbooks with multiple (sub-)tasks file, it becomes -difficult to understand which task belongs to which file. Adding a prefix, in -combination with the role’s name automatically added by Ansible, makes it a -lot easier to follow and troubleshoot a role play. -``` +!!! note + + This rule was designed by [Red Hat Community of Practice](https://redhat-cop.github.io/automation-good-practices/#_prefix_task_names_in_sub_tasks_files_of_roles). The reasoning behind it being + that in a complex roles or playbooks with multiple (sub-)tasks file, it becomes + difficult to understand which task belongs to which file. Adding a prefix, in + combination with the role’s name automatically added by Ansible, makes it a + lot easier to follow and troubleshoot a role play. ## Problematic code diff --git a/src/ansiblelint/rules/no_free_form.md b/src/ansiblelint/rules/no_free_form.md index c6f5486687..b5317c15fe 100644 --- a/src/ansiblelint/rules/no_free_form.md +++ b/src/ansiblelint/rules/no_free_form.md @@ -1,22 +1,23 @@ # no-free-form -This rule identifies any use of [free-form](https://docs.ansible.com/ansible/2.7/user_guide/playbooks_intro.html#action-shorthand) +This rule identifies any use of +[free-form](https://docs.ansible.com/ansible/2.7/user_guide/playbooks_intro.html#action-shorthand) module calling syntax and asks for switching to the full syntax. **Free-form** syntax, also known as **inline** or **shorthand**, can produce subtle bugs. It can also prevent editors and IDEs from providing feedback, autocomplete and validation for the edited line. -```{note} -As long you just pass a YAML string that contains a `=` character inside as the -parameter to the action module name, we consider this as using free-formsyntax. -Be sure you pass a dictionary to the module, so the free-form parsing -is never triggered. -``` +!!! note + + As long you just pass a YAML string that contains a `=` character inside as the + parameter to the action module name, we consider this as using free-formsyntax. + Be sure you pass a dictionary to the module, so the free-form parsing is never + triggered. As `raw` module only accepts free-form, we trigger `no-free-form[raw]` only if -we detect the presence of `executable=` inside raw calls. We advice the -explicit use of `args:` dictionary for configuring the executable to be run. +we detect the presence of `executable=` inside raw calls. We advice the explicit +use of `args:` dictionary for configuring the executable to be run. ## Problematic code diff --git a/src/ansiblelint/rules/no_relative_paths.md b/src/ansiblelint/rules/no_relative_paths.md index a22a9c1552..568a1455aa 100644 --- a/src/ansiblelint/rules/no_relative_paths.md +++ b/src/ansiblelint/rules/no_relative_paths.md @@ -1,27 +1,35 @@ # no-relative-paths -This rule checks for relative paths in the `ansible.builtin.copy` and `ansible.builtin.template` modules. +This rule checks for relative paths in the `ansible.builtin.copy` and +`ansible.builtin.template` modules. -Relative paths in a task most often direct Ansible to remote files and directories on managed nodes. -In the `ansible.builtin.copy` and `ansible.builtin.template` modules, the `src` argument refers to local files and directories on the control node. +Relative paths in a task most often direct Ansible to remote files and +directories on managed nodes. In the `ansible.builtin.copy` and +`ansible.builtin.template` modules, the `src` argument refers to local files and +directories on the control node. The recommended locations to store files are as follows: -- Use the `files/` folder in the playbook or role directory for the `copy` module. -- Use the `templates/` folder in the playbook or role directory for the `template` module. +- Use the `files/` folder in the playbook or role directory for the `copy` + module. +- Use the `templates/` folder in the playbook or role directory for the + `template` module. -These folders allow you to omit the path or use a sub-folder when specifying files with the `src` argument. +These folders allow you to omit the path or use a sub-folder when specifying +files with the `src` argument. -```{note} -If resources are outside your Ansible playbook or role directory you should use an absolute path with the `src` argument. -``` +!!! note -```{warning} -Do not store resources at the same directory level as your Ansible playbook or tasks files. -Doing this can result in disorganized projects and cause user confusion when distinguishing between resources of the same type, such as YAML. -``` + If resources are outside your Ansible playbook or role directory you should use an absolute path with the `src` argument. + +!!! warning + + Do not store resources at the same directory level as your Ansible playbook or tasks files. + Doing this can result in disorganized projects and cause user confusion when distinguishing between resources of the same type, such as YAML. -See [task paths](https://docs.ansible.com/ansible/latest/playbook_guide/playbook_pathing.html#task-paths) in the Ansible documentation for more information. +See +[task paths](https://docs.ansible.com/ansible/latest/playbook_guide/playbook_pathing.html#task-paths) +in the Ansible documentation for more information. ## Problematic Code diff --git a/src/ansiblelint/rules/no_tabs.md b/src/ansiblelint/rules/no_tabs.md index 53a61d9125..7895122cc7 100644 --- a/src/ansiblelint/rules/no_tabs.md +++ b/src/ansiblelint/rules/no_tabs.md @@ -1,12 +1,12 @@ # no-tabs -This rule checks for the tab character. -The `\t` tab character can result in unexpected display or formatting issues. -You should always use spaces instead of tabs. +This rule checks for the tab character. The `\t` tab character can result in +unexpected display or formatting issues. You should always use spaces instead of +tabs. -```{note} -This rule does not trigger alerts for tab characters in the ``ansible.builtin.lineinfile`` module. -``` +!!! note + + This rule does not trigger alerts for tab characters in the ``ansible.builtin.lineinfile`` module. ## Problematic Code diff --git a/src/ansiblelint/rules/partial_become.md b/src/ansiblelint/rules/partial_become.md index 1b328fe014..01f9dae546 100644 --- a/src/ansiblelint/rules/partial_become.md +++ b/src/ansiblelint/rules/partial_become.md @@ -2,15 +2,16 @@ This rule checks that privilege escalation is activated when changing users. -To perform an action as a different user with the `become_user` directive, you must set `become: true`. - -```{warning} -While Ansible inherits have of `become` and `become_user` from upper levels, -like play level or command line, we do not look at these values. This rule -requires you to be explicit and always define both in the same place, mainly -in order to prevent accidents when some tasks are moved from one location to -another one. -``` +To perform an action as a different user with the `become_user` directive, you +must set `become: true`. + +!!! warning + + While Ansible inherits have of `become` and `become_user` from upper levels, + like play level or command line, we do not look at these values. This rule + requires you to be explicit and always define both in the same place, mainly + in order to prevent accidents when some tasks are moved from one location to + another one. ## Problematic Code diff --git a/src/ansiblelint/rules/risky_file_permissions.md b/src/ansiblelint/rules/risky_file_permissions.md index 30a12f2999..a04e12d3b2 100644 --- a/src/ansiblelint/rules/risky_file_permissions.md +++ b/src/ansiblelint/rules/risky_file_permissions.md @@ -1,16 +1,16 @@ # risky-file-permissions This rule is triggered by various modules that could end up creating new files -on disk with permissions that might be too open, or unpredictable. Please -read the documentation of each module carefully to understand the -implications of using different argument values, as these make the difference -between using the module safely or not. The fix depends on each module and -also your particular situation. +on disk with permissions that might be too open, or unpredictable. Please read +the documentation of each module carefully to understand the implications of +using different argument values, as these make the difference between using the +module safely or not. The fix depends on each module and also your particular +situation. Some modules have a `create` argument that defaults to `true`. For those you -either need to set `create: false` or provide some permissions like -`mode: 0600` to make the behavior predictable and not dependent on the current -system settings. +either need to set `create: false` or provide some permissions like `mode: 0600` +to make the behavior predictable and not dependent on the current system +settings. Modules that are checked: @@ -23,10 +23,10 @@ Modules that are checked: - [`community.general.archive`](https://docs.ansible.com/ansible/latest/collections/community/general/archive_module.html) - [`community.general.ini_file`](https://docs.ansible.com/ansible/latest/collections/community/general/ini_file_module.html) -```{warning} -This rule does not take [module_defaults](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_module_defaults.html) configuration into account. -There are currently no plans to implement this feature because changing task location can also change task behavior. -``` +!!! warning + + This rule does not take [module_defaults](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_module_defaults.html) configuration into account. + There are currently no plans to implement this feature because changing task location can also change task behavior. ## Problematic code diff --git a/src/ansiblelint/rules/run_once.md b/src/ansiblelint/rules/run_once.md index 5621d2939a..6b14703f89 100644 --- a/src/ansiblelint/rules/run_once.md +++ b/src/ansiblelint/rules/run_once.md @@ -5,7 +5,8 @@ This rule warns against the use of `run_once` when `strategy` is set to `free`. This rule can produce the following messages: - `run_once[play]`: Play uses `strategy: free`. -- `run_once[task]`: Using `run_once` may behave differently if `strategy` is set to `free`. +- `run_once[task]`: Using `run_once` may behave differently if `strategy` is set + to `free`. For more information see the following topics in Ansible documentation: @@ -13,11 +14,12 @@ For more information see the following topics in Ansible documentation: - [selecting a strategy](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_strategies.html#selecting-a-strategy) - [run_once(playbook keyword) more info](https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html) -```{warning} -This rule will always trigger regardless of the value configured inside 'strategy' field. That is because the effective value used at runtime can be different than the value inside the file. For example, ansible command line arguments can alter it. -``` +!!! warning + + This rule will always trigger regardless of the value configured inside 'strategy' field. That is because the effective value used at runtime can be different than the value inside the file. For example, ansible command line arguments can alter it. -It is perfectly fine to add `# noqa: run_once[task]` to mark the warning as acknowledged and ignored. +It is perfectly fine to add `# noqa: run_once[task]` to mark the warning as +acknowledged and ignored. ## Problematic Code @@ -52,7 +54,7 @@ It is perfectly fine to add `# noqa: run_once[task]` to mark the warning as ackn strategy: linear gather_facts: false tasks: # <-- use noqa to disable rule violations for specific tasks - - name: Task with run_once # noqa: run_once[task] + - name: Task with run_once # noqa: run_once[task] ansible.builtin.debug: msg: "Test" run_once: true diff --git a/tox.ini b/tox.ini index bf06627e24..25f3ab825f 100644 --- a/tox.ini +++ b/tox.ini @@ -121,41 +121,16 @@ commands = [testenv:docs] description = Builds docs -deps = - --editable .[docs,test] +extras = + docs +setenv = + # Disable colors until markdown-exec supports it: + # https://github.com/pawamoy/markdown-exec/issues/11 + NO_COLOR = 1 +skip_install = false +usedevelop = true commands = - # regenerate docs for rules - sh -c "cd {toxinidir} && ansible-lint -L -f docs" - sh -c "rm -f {toxinidir}/docs/pkg/*.rst" - {envpython} -m sphinx \ - -j auto \ - -b linkcheck \ - -a \ - -n \ - -W --keep-going \ - {tty:--color} \ - -d "{envdir}/.doctrees" \ - . \ - "{envdir}/html" - - # Build the html docs with Sphinx: - {envpython} -m sphinx \ - -j auto \ - -b html \ - --color \ - -a \ - -n \ - -W --keep-going \ - -d "{envdir}/.doctrees" \ - . \ - "{envdir}/html" - - # Print out the output docs dir and a way to serve html: - - {envpython} -c \ - 'import pathlib, webbrowser; docs_dir = pathlib.Path(r"{envdir}") / "html"; index_file = docs_dir / "index.html"; '\ - 'print(f"\nTo serve docs, use `python3 -m http.server --directory \{docs_dir\} 0`\n"); webbrowser.open(f"file://\{index_file\}")' - -changedir = {toxinidir}/docs + mkdocs build {posargs:} [testenv:redirects] description = Update documentation redirections for readthedocs