diff --git a/.config/dictionary.txt b/.config/dictionary.txt index 1b633b2bca3..d32df04fa90 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 03e0b588a79..0111d6a8f5b 100644 --- a/.config/requirements-docs.txt +++ b/.config/requirements-docs.txt @@ -1,8 +1,10 @@ -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 +mkdocs +mkdocs-gen-files +mkdocs-material +mkdocs-material-extensions +mkdocstrings +mkdocstrings-python +pillow +pymdown-extensions diff --git a/.config/requirements.txt b/.config/requirements.txt index c273a5d80e5..c76aba80db2 100644 --- a/.config/requirements.txt +++ b/.config/requirements.txt @@ -4,48 +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 -pipdeptree==2.3.3 +pillow==9.4.0 platformdirs==2.6.2 pluggy==1.0.0 psutil==5.9.4 @@ -54,37 +63,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 f9781070b5d..00000000000 --- 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 81fb714dcc9..b03c3a62a96 100644 --- a/.gitignore +++ b/.gitignore @@ -68,3 +68,4 @@ docs/profiles.md test/schemas/node_modules .envrc collections +site diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0bdd0026020..57006b3a009 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 1cfd9b82ec1..f4d728306ed 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,52 +1,22 @@ -# 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 - 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 +python: + system_packages: false + install: + - method: pip + path: tox + - method: pip + path: . + extra_requirements: + - docs diff --git a/ANSI-Test.sh b/ANSI-Test.sh new file mode 100755 index 00000000000..b84cfdd5c02 --- /dev/null +++ b/ANSI-Test.sh @@ -0,0 +1,71 @@ +# ANSI Start Codes + +# Styles. +Normal="\x1b[0m" +Bold="\x1b[1m" +Faint="\x1b[2m" +Italic="\x1b[3m" +Underline="\x1b[4m" +Blink_Slow="\x1b[5m" +Blink_Rapid="\x1b[6m" +Inverse="\x1b[7m" +Conceal="\x1b[8m" +Crossed_Out="\x1b[9m" +# Text colors. +Black="\x1b[30m" +Red="\x1b[31m" +Green="\x1b[32m" +Yellow="\x1b[33m" +Blue="\x1b[34m" +Magenta="\x1b[35m" +Cyan="\x1b[36m" +White="\x1b[37m" +# Background colors. +Bg_Black="\x1b[40m" +Bg_Red="\x1b[41m" +Bg_Green="\x1b[42m" +Bg_Yellow="\x1b[43m" +Bg_Blue="\x1b[44m" +Bg_Magenta="\x1b[45m" +Bg_Cyan="\x1b[46m" +Bg_White="\x1b[47m" +# Resets +NoStyle="\x1b[0m" +NoUnderline="\x1b[24m" +NoInverse="\x1b[27m" +NoColor="\x1b[39m" + +Colors1="None $Black""Black""$NoColor $Red""Red""$NoColor $Green""Green""$NoColor $Yellow""Yellow""$NoColor" +Colors2="$Blue""Blue""$NoColor $Magenta""Magenta""$NoColor $Cyan""Cyan""$NoColor $White""White""$NoColor" +AllColors="$Colors1 $Colors2 $NoStyle" + +Bg_Black_All="$Bg_Black$AllColors" +Bg_Red_All="$Bg_Red$AllColors" +Bg_Green_All="$Bg_Green$AllColors" +Bg_Yellow_All="$Bg_Yellow$AllColors" +Bg_Blue_All="$Bg_Blue$AllColors" +Bg_Magenta_All="$Bg_Magenta$AllColors" +Bg_Cyan_All="$Bg_Cyan$AllColors" +Bg_White_All="$Bg_White$AllColors" + +# Test Table +echo "Background: | Style: | Text Colors:" +echo "------------|-------------|----------------------------------------------------" +echo " | Normal | "$Normal$AllColors +echo " | Bold | "$Bold$AllColors +echo " | Faint | "$Faint$AllColors +echo " | Italic | "$Italic$AllColors +echo " | Underline | "$Underline$AllColors +echo " | Blink_Slow | "$Blink_Slow$AllColors +echo " | Blink_Rapid | "$Blink_Rapid$AllColors +echo " | Inverse | "$Inverse$AllColors +echo " | Conceal | "$Conceal$AllColors +echo " | Crossed_Out | "$Crossed_Out$AllColors +echo "BG Black | Normal | "$Normal$Bg_Black_All +echo "BG Red | Normal | "$Normal$Bg_Red_All +echo "BG Green | Normal | "$Normal$Bg_Green_All +echo "BG Yellow | Normal | "$Normal$Bg_Yellow_All +echo "BG Blue | Normal | "$Normal$Bg_Blue_All +echo "BG Magenta | Normal | "$Normal$Bg_Magenta_All +echo "BG Cyan | Normal | "$Normal$Bg_Cyan_All +echo "BG White | Normal | "$Normal$Bg_White_All diff --git a/a.ansi b/a.ansi new file mode 100644 index 00000000000..62588d28c6c --- /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 b84f66817e2..00000000000 --- 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 98eee828960..00000000000 --- 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 4976baed76a..49deb3d4e39 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 91e00911018..ebd19711c10 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 b752b758b7d..8c57d90c317 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 00000000000..ef63d772953 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 00000000000..2d23c7e04cc 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 00000000000..ffe210b6d78 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/installing.md b/docs/installing.md index b63731f9e8e..026b580d684 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/rules.md b/docs/rules.md deleted file mode 100644 index a0f942ec872..00000000000 --- a/docs/rules.md +++ /dev/null @@ -1,10 +0,0 @@ -(lint-rules)= - -# Rules - -```{toctree} -:maxdepth: 1 -:glob: - -rules/* -``` diff --git a/docs/rules/index.md b/docs/rules/index.md new file mode 100644 index 00000000000..d5779e391f0 --- /dev/null +++ b/docs/rules/index.md @@ -0,0 +1,60 @@ +# 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-builtins][] +- [fqcn][] +- [galaxy][] +- [git-latest][] +- [hg-latest][] +- [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][] +- [module-options][] +- [name][] +- [no-changed-when][] +- [no-free-form][] +- [no-handler][] +- [no-jinja-nesting][] +- [no-jinja-when][] +- [no-log-password][] +- [no-loop-var-prefix][] +- [no-prompting][] +- [no-relative-paths][] +- [no-same-owner][] +- [no-shorthand][] +- [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][] +- [template-instead-of-copy][] +- [var-naming][] +- [warning][] +- [yaml][] diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000000..9b14d833ebb --- /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 f3cd1f065a2..28aa7c84174 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,18 +1,36 @@ -(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. + +```ansi +Background: | Style: | Text Colors: +------------|-------------|---------------------------------------------------- + | Normal | None Black Red Green Yellow Blue Magenta Cyan White  + | Bold | None Black Red Green Yellow Blue Magenta Cyan White  + | Faint | None Black Red Green Yellow Blue Magenta Cyan White  + | Italic | None Black Red Green Yellow Blue Magenta Cyan White  + | Underline | None Black Red Green Yellow Blue Magenta Cyan White  + | Blink_Slow | None Black Red Green Yellow Blue Magenta Cyan White  + | Blink_Rapid | None Black Red Green Yellow Blue Magenta Cyan White  + | Inverse | None Black Red Green Yellow Blue Magenta Cyan White  + | Conceal | None Black Red Green Yellow Blue Magenta Cyan White  + | Crossed_Out | None Black Red Green Yellow Blue Magenta Cyan White  +BG Black | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG Red | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG Green | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG Yellow | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG Blue | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG Magenta | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG Cyan | Normal | None Black Red Green Yellow Blue Magenta Cyan White  +BG White | Normal | None Black Red Green Yellow Blue Magenta Cyan White  -```{command-output} ansible-lint --help - :cwd: .. - :returncode: 0 +``` + +```bash exec="1" source="console" +ansible-lint --help ``` ### Command output @@ -22,108 +40,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 --force-color --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 +164,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 +205,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 diff --git a/docs/using-profiles.md b/docs/using-profiles.md index 396cae5b348..8d6bb7fda44 100644 --- a/docs/using-profiles.md +++ b/docs/using-profiles.md @@ -1,21 +1,24 @@ -(using-lint-profiles)= - # Applying profiles -Ansible-lint profiles allow content creators to progressively improve the quality of Ansible playbooks, roles, and collections. +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. -``` +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: +After you install and configure `ansible-lint`, you can apply profiles as +follows: 1. View available profiles with the `--list-profiles` flag. @@ -23,7 +26,8 @@ After you install and configure `ansible-lint`, you can apply profiles as follow ansible-lint --list-profiles ``` -2. Specify a profile with the `--profile` parameter to lint your content with those rules, for example: +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. @@ -31,7 +35,8 @@ After you install and configure `ansible-lint`, you can apply profiles as follow ansible-lint --profile=basic ``` -- Ensure automation consistency, reliability, and security with the `safety` profile. +- Ensure automation consistency, reliability, and security with the `safety` + profile. ```bash ansible-lint --profile=safety diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000000..17200ef7813 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,192 @@ +--- +site_name: Ansible List +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/github-alt + link: https://github.com/ansible/ansible-lint + +nav: + - User Guide: + - home: index.md + - philosophy.md + - installing.md + - usage.md + - configuring.md + - using-profiles.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-builtins.md + - rules/fqcn.md + - rules/galaxy.md + - rules/git-latest.md + - rules/hg-latest.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/module-options.md + - rules/name.md + - rules/no-changed-when.md + - rules/no-free-form.md + - rules/no-handler.md + - rules/no-jinja-nesting.md + - rules/no-jinja-when.md + - rules/no-log-password.md + - rules/no-loop-var-prefix.md + - rules/no-prompting.md + - rules/no-relative-paths.md + - rules/no-same-owner.md + - rules/no-shorthand.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/template-instead-of-copy.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: + # - python3 -m ansiblelint -L -f docs + - 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] + # - https://virtualenv.pypa.io/en/latest/objects.inv + # - https://yamllint.readthedocs.io/en/latest/objects.inv + # - https://jinja.palletsprojects.com/objects.inv + # - https://pip.pypa.io/en/latest/objects.inv + # - https://docs.python.org/3/objects.inv + # - https://testinfra.readthedocs.io/en/latest/objects.inv + +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 # ...one fence for each language we support: diff --git a/pyproject.toml b/pyproject.toml index a70bf1f0097..81080f5553c 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/generate_docs.py b/src/ansiblelint/generate_docs.py index 132e33c4375..76cbfbbff67 100644 --- a/src/ansiblelint/generate_docs.py +++ b/src/ansiblelint/generate_docs.py @@ -134,9 +134,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/tox.ini b/tox.ini index bf06627e243..2cc9706394f 100644 --- a/tox.ini +++ b/tox.ini @@ -121,41 +121,14 @@ commands = [testenv:docs] description = Builds docs -deps = - --editable .[docs,test] +extras = + docs +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 [testenv:redirects] description = Update documentation redirections for readthedocs