20 files changed, 723 insertions, 0 deletions
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..22695c6
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,16 @@
+# Old compiled python stuff
+*.py[co]
+# package building stuff
+build
+# Emacs backup files...
+*~
+.\#*
+.doctrees
+# Generated docs stuff
+ansible*.xml
+.buildinfo
+objects.inv
+.doctrees
+*.min.css
+_build
+rst_warnings
diff --git a/docs/.nojekyll b/docs/.nojekyll
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..b84f668
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,9 @@
+# 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/_static/ansible-lint.svg b/docs/_static/ansible-lint.svg
new file mode 100644
index 0000000..e1270a8
--- /dev/null
+++ b/docs/_static/ansible-lint.svg
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 64 64" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:1.5;">
+    <g transform="matrix(1,0,0,1,-67.7268,-0.0813272)">
+        <g id="ansible-lint" transform="matrix(0.103624,0,0,0.0970726,-51.3462,16.5365)">
+            <rect x="1149.09" y="-169.514" width="617.619" height="659.3" style="fill:none;"/>
+            <g transform="matrix(-9.64401,0.0125512,-0.0123169,-10.7844,1789.35,505.457)">
+                <path d="M34.404,5.547C56.248,14.75 62.901,29.008 62.864,58.451C48.638,53.766 48.041,53.62 34.295,58.418C19.563,53.502 19.058,53.483 6.355,58.386C6.392,29.206 14.197,15.017 34.404,5.547Z" style="fill:rgb(128,128,128);stroke:rgb(128,128,128);stroke-width:3.91px;"/>
+            </g>
+            <g transform="matrix(2.86444,0,0,3.05775,1016.6,-336.23)">
+                <path d="M154.799,112.893L182.438,181.102L140.692,148.221L154.799,112.893ZM203.895,196.815L161.385,94.514C160.385,91.762 157.727,89.94 154.799,90.001C151.826,89.933 149.113,91.743 148.034,94.514L101.377,206.726L117.338,206.726L135.806,160.458L190.923,204.988C193.142,206.782 194.739,207.593 196.82,207.593C196.88,207.594 196.939,207.595 196.999,207.595C201.181,207.595 204.623,204.153 204.623,199.97C204.623,199.968 204.623,199.966 204.623,199.964C204.551,198.882 204.305,197.819 203.895,196.815" style="fill:white;fill-rule:nonzero;"/>
+            </g>
+        </g>
+    </g>
+</svg>
diff --git a/docs/_static/images/logo_invert.png b/docs/_static/images/logo_invert.png
new file mode 100644
index 0000000..dfeba66
--- /dev/null
+++ b/docs/_static/images/logo_invert.png
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
new file mode 100644
index 0000000..2eea3ee
--- /dev/null
+++ b/docs/_static/theme_overrides.css
@@ -0,0 +1,15 @@
+/* table width fix via: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */
+
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+ *          this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..9a911ed
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,256 @@
+# -*- coding: utf-8 -*-
+#
+# 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."""
+
+import os
+import sys
+from pathlib import Path
+
+# 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()))
+
+# pip 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 = '2.6'
+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',
+    'sphinxcontrib.programoutput',
+    'rules_table_generator_ext',  # in-tree extension
+]
+
+# 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'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Ansible Lint Documentation'
+copyright = "2013-2020 Ansible, Inc"
+
+# 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 = '%B %d, %Y'
+
+# 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 = 'sphinx'
+
+highlight_language = 'YAML+Jinja'
+
+# Substitutions, variables, entities, & shortcuts for text which do not need to link to anything.
+# For titles which should be a link, use the intersphinx anchors set at the index, chapter, and
+# section levels, such as  qi_start_:
+rst_epilog = """
+.. |acapi| replace:: *Ansible Core API Guide*
+.. |acrn| replace:: *Ansible Core Release Notes*
+.. |ac| replace:: Ansible Core
+.. |acversion| replace:: Ansible Core Version 2.1
+.. |acversionshort| replace:: Ansible Core 2.1
+.. |versionshortest| replace:: 2.2
+.. |versiondev| replace:: 2.3
+.. |pubdate| replace:: July 19, 2016
+.. |rhel| replace:: Red Hat Enterprise Linux
+
+"""
+
+
+# Options for HTML output
+# -----------------------
+
+html_theme_path = ['../_themes']
+html_theme = 'sphinx_ansible_theme'
+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
+# "<project> v<release> 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.
+# html_logo = None
+
+# 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.
+html_favicon = '_static/ansible-lint.svg'
+
+# 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/<name>.
+html_copy_source = False
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> 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/en/latest/'
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Poseidodoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class
+# [howto/manual]).
+latex_documents = [
+    ('index', 'ansible.tex', 'Ansible 2.2 Documentation', AUTHOR, 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True
+
+autoclass_content = 'both'
+
+intersphinx_mapping = {'python': ('https://docs.python.org/2/', (None, '../python2-2.7.13.inv')),
+                       'python3': ('https://docs.python.org/3/', (None, '../python3-3.6.2.inv')),
+                       'jinja2': ('http://jinja.pocoo.org/docs/', (None, '../jinja2-2.9.7.inv'))}
+
+
+# table width fix via: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
+html_static_path = ['_static']
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+    ],
+}
diff --git a/docs/configuring.rst b/docs/configuring.rst
new file mode 100644
index 0000000..fac77d3
--- /dev/null
+++ b/docs/configuring.rst
@@ -0,0 +1,14 @@
+
+.. _configuring_lint:
+
+***********
+Configuring
+***********
+
+.. contents:: Topics
+
+This topic describes how to configure Ansible Lint
+
+.. include:: ../README.rst
+   :start-after: configuring-docs-inclusion-marker-do-not-remove
+   :end-before: configuring-docs-inclusion-marker-end-do-not-remove
diff --git a/docs/contributing.rst b/docs/contributing.rst
new file mode 100644
index 0000000..3f0d3bb
--- /dev/null
+++ b/docs/contributing.rst
@@ -0,0 +1,50 @@
+.. include:: ../.github/CONTRIBUTING.rst
+   :end-before: DO-NOT-REMOVE-deps-snippet-PLACEHOLDER
+
+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.
+
+.. command-output:: pipdeptree -p ansible-lint
+
+.. include:: ../.github/CONTRIBUTING.rst
+   :start-after: DO-NOT-REMOVE-deps-snippet-PLACEHOLDER
+
+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:
+
+* 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_ page and pick one that matches the best your new rule.
+  see 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
+  to look at how similar rules were implemented to figure out what to do.
+* Update the tests. It must have at least one test and likely also a negative
+  match one.
+* If the rule is task specific, it may be best to include a test to verify its
+  use inside blocks as well.
+* Optionally run only the rule specific tests with a command like:
+  :command:`tox -e py38-ansible29 -- -k NewRule`
+* Run :command:`tox` in order to run all ansible-lint tests. Adding a new rule
+  can break some other tests. Update them if needed.
+* Run :command:`ansible-lint -L` and check that the rule description renders
+  correctly.
+* 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/master/lib/ansiblelint/rules/MetaTagValidRule.py
+.. _rules: https://ansible-lint.readthedocs.io/en/latest/default_rules.html
diff --git a/docs/default_rules.rst b/docs/default_rules.rst
new file mode 100644
index 0000000..daf66a0
--- /dev/null
+++ b/docs/default_rules.rst
@@ -0,0 +1 @@
+.. ansible-lint-default-rules-list::
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..3836198
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,47 @@
+.. _lint_documentation:
+
+Ansible Lint Documentation
+==========================
+
+About Ansible Lint
+``````````````````
+
+Ansible Lint is a commandline tool for linting playbooks. Use it to detect behaviors and practices that could potentially
+be improved.
+
+The tool is used by the `Ansible Galaxy project <https://github.com/ansible/galaxy/>`_ to lint and calculate quality scores
+for content contributed to the `Galaxy Hub <https://galaxy.ansible.com>`_.
+
+The project was originally started by `@willthames <https://github.com/willthames/>`_, and has since been
+transferred to the Ansible project team.
+
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Installing
+
+   installing
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Usage
+
+   usage
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Configuring
+
+   configuring
+
+.. toctree::
+   :maxdepth: 4
+   :caption: Rules
+
+   rules
+   default_rules
+
+.. toctree::
+   :caption: Contributing
+
+   contributing
diff --git a/docs/installing.rst b/docs/installing.rst
new file mode 100644
index 0000000..1b84abd
--- /dev/null
+++ b/docs/installing.rst
@@ -0,0 +1,15 @@
+
+.. _installing_lint:
+
+
+**********
+Installing
+**********
+
+.. contents:: Topics
+
+This topic describes how to install Ansible Lint.
+
+.. include:: ../README.rst
+   :start-after: installing-docs-inclusion-marker-do-not-remove
+   :end-before: installing-docs-inclusion-marker-end-do-not-remove
diff --git a/docs/jinja2-2.9.7.inv b/docs/jinja2-2.9.7.inv
new file mode 100644
index 0000000..a45888b
--- /dev/null
+++ b/docs/jinja2-2.9.7.inv
diff --git a/docs/python2-2.7.13.inv b/docs/python2-2.7.13.inv
new file mode 100644
index 0000000..ab7587f
--- /dev/null
+++ b/docs/python2-2.7.13.inv
diff --git a/docs/python3-3.6.2.inv b/docs/python3-3.6.2.inv
new file mode 100644
index 0000000..1d2ed4e
--- /dev/null
+++ b/docs/python3-3.6.2.inv
diff --git a/docs/requirements.in b/docs/requirements.in
new file mode 100644
index 0000000..9ed90dd
--- /dev/null
+++ b/docs/requirements.in
@@ -0,0 +1,5 @@
+myst-parser
+pipdeptree
+Sphinx
+sphinx_ansible_theme
+sphinxcontrib.programoutput
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..4820753
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,184 @@
+#
+# This file is autogenerated by pip-compile
+# To update, run:
+#
+#    pip-compile --generate-hashes --output-file=docs/requirements.txt docs/requirements.in
+#
+alabaster==0.7.12 \
+    --hash=sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359 \
+    --hash=sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02 \
+    # via sphinx
+attrs==19.3.0 \
+    --hash=sha256:08a96c641c3a74e44eb59afb61a24f2cb9f4d7188748e76ba4bb5edfa3cb7d1c \
+    --hash=sha256:f7b7ce16570fe9965acd6d30101a28f62fb4a7f9e926b3bbc9b61f8b04247e72 \
+    # via markdown-it-py
+babel==2.8.0 \
+    --hash=sha256:1aac2ae2d0d8ea368fa90906567f5c08463d98ade155c0c4bfedd6a0f7160e38 \
+    --hash=sha256:d670ea0b10f8b723672d3a6abeb87b565b244da220d76b4dba1b66269ec152d4 \
+    # via sphinx
+certifi==2020.6.20 \
+    --hash=sha256:5930595817496dd21bb8dc35dad090f1c2cd0adfaf21204bf6732ca5d8ee34d3 \
+    --hash=sha256:8fc0819f1f30ba15bdb34cceffb9ef04d99f420f68eb75d901e9560b8749fc41 \
+    # via requests
+chardet==3.0.4 \
+    --hash=sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae \
+    --hash=sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691 \
+    # via requests
+docutils==0.16 \
+    --hash=sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af \
+    --hash=sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc \
+    # via myst-parser, sphinx
+idna==2.10 \
+    --hash=sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6 \
+    --hash=sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0 \
+    # via requests
+imagesize==1.2.0 \
+    --hash=sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1 \
+    --hash=sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1 \
+    # via sphinx
+jinja2==2.11.2 \
+    --hash=sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0 \
+    --hash=sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035 \
+    # via sphinx
+markdown-it-py==0.5.4 \
+    --hash=sha256:d1782446f7fcbf2db9a1bc0430230cb879498ad6d76168d7e7c762bab04cb4ea \
+    --hash=sha256:f18ec8f1c1a424ab2a9ac06b5ba87d6d2a01e450cd8678edbc71002106dd68a8 \
+    # via myst-parser
+markupsafe==1.1.1 \
+    --hash=sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473 \
+    --hash=sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161 \
+    --hash=sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235 \
+    --hash=sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5 \
+    --hash=sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42 \
+    --hash=sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff \
+    --hash=sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b \
+    --hash=sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1 \
+    --hash=sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e \
+    --hash=sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183 \
+    --hash=sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66 \
+    --hash=sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b \
+    --hash=sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1 \
+    --hash=sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15 \
+    --hash=sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1 \
+    --hash=sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e \
+    --hash=sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b \
+    --hash=sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905 \
+    --hash=sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735 \
+    --hash=sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d \
+    --hash=sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e \
+    --hash=sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d \
+    --hash=sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c \
+    --hash=sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21 \
+    --hash=sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2 \
+    --hash=sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5 \
+    --hash=sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b \
+    --hash=sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6 \
+    --hash=sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f \
+    --hash=sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f \
+    --hash=sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2 \
+    --hash=sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7 \
+    --hash=sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be \
+    # via jinja2
+myst-parser==0.12.10 \
+    --hash=sha256:4612c46196e0344bb7e49dbc3deb288f9b9a88fcf6e9f210f7f3ea5bc9899bfc \
+    --hash=sha256:a5311da4398869e596250d5a93b523735c3beb8bc9d3eba853223c705802043b \
+    # via -r requirements.in
+packaging==20.4 \
+    --hash=sha256:4357f74f47b9c12db93624a82154e9b120fa8293699949152b22065d556079f8 \
+    --hash=sha256:998416ba6962ae7fbd6596850b80e17859a5753ba17c32284f67bfff33784181 \
+    # via sphinx
+pipdeptree==1.0.0 \
+    --hash=sha256:35a81058c9568a29c5a9569109304b25f11cd9333fa2661a4d4c2c5da0e3939d \
+    --hash=sha256:5fe866a38113d28d527033ececc57b8e86df86b7c29edbacb33f41ee50f75b31 \
+    --hash=sha256:a7e4f744f3ae149cf94dd5e517fae682780c4729f4a279e6fb81a928f57fea23 \
+    # via -r requirements.in
+pygments==2.6.1 \
+    --hash=sha256:647344a061c249a3b74e230c739f434d7ea4d8b1d5f3721bc0f3558049b38f44 \
+    --hash=sha256:ff7a40b4860b727ab48fad6360eb351cc1b33cbf9b15a0f689ca5353e9463324 \
+    # via sphinx
+pyparsing==2.4.7 \
+    --hash=sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1 \
+    --hash=sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b \
+    # via packaging
+pytz==2020.1 \
+    --hash=sha256:a494d53b6d39c3c6e44c3bec237336e14305e4f29bbf800b599253057fbb79ed \
+    --hash=sha256:c35965d010ce31b23eeb663ed3cc8c906275d6be1a34393a1d73a41febf4a048 \
+    # via babel
+pyyaml==5.3.1 \
+    --hash=sha256:06a0d7ba600ce0b2d2fe2e78453a470b5a6e000a985dd4a4e54e436cc36b0e97 \
+    --hash=sha256:240097ff019d7c70a4922b6869d8a86407758333f02203e0fc6ff79c5dcede76 \
+    --hash=sha256:4f4b913ca1a7319b33cfb1369e91e50354d6f07a135f3b901aca02aa95940bd2 \
+    --hash=sha256:69f00dca373f240f842b2931fb2c7e14ddbacd1397d57157a9b005a6a9942648 \
+    --hash=sha256:73f099454b799e05e5ab51423c7bcf361c58d3206fa7b0d555426b1f4d9a3eaf \
+    --hash=sha256:74809a57b329d6cc0fdccee6318f44b9b8649961fa73144a98735b0aaf029f1f \
+    --hash=sha256:7739fc0fa8205b3ee8808aea45e968bc90082c10aef6ea95e855e10abf4a37b2 \
+    --hash=sha256:95f71d2af0ff4227885f7a6605c37fd53d3a106fcab511b8860ecca9fcf400ee \
+    --hash=sha256:b8eac752c5e14d3eca0e6dd9199cd627518cb5ec06add0de9d32baeee6fe645d \
+    --hash=sha256:cc8955cfbfc7a115fa81d85284ee61147059a753344bc51098f3ccd69b0d7e0c \
+    --hash=sha256:d13155f591e6fcc1ec3b30685d50bf0711574e2c0dfffd7644babf8b5102ca1a \
+    # via myst-parser
+requests==2.24.0 \
+    --hash=sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b \
+    --hash=sha256:fe75cc94a9443b9246fc7049224f75604b113c36acb93f87b80ed42c44cbb898 \
+    # via sphinx
+six==1.15.0 \
+    --hash=sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259 \
+    --hash=sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced \
+    # via packaging
+snowballstemmer==2.0.0 \
+    --hash=sha256:209f257d7533fdb3cb73bdbd24f436239ca3b2fa67d56f6ff88e86be08cc5ef0 \
+    --hash=sha256:df3bac3df4c2c01363f3dd2cfa78cce2840a79b9f1c2d2de9ce8d31683992f52 \
+    # via sphinx
+sphinx-ansible-theme==0.3.2 \
+    --hash=sha256:250e46bc318062a2e95cc55db5dfecddb5f847f38d672d487162920f3f3ae205 \
+    --hash=sha256:424ec6fbc61bc8bba3e6eb482d3ceb92e6e2d80d7e8e06599e2bbc856026feaf \
+    # via -r requirements.in
+sphinx-notfound-page==0.4 \
+    --hash=sha256:0105a40d8a305d3e1003630d8ee99296baa08cf2a4c1ce1db8d91fbbe78f90db \
+    --hash=sha256:609fd7cd7f9ea73c030f1b67a3f2bc90f60bff87b30026fbd2bcb19c7c59c484 \
+    # via sphinx-ansible-theme
+sphinx-rtd-theme==0.5.0 \
+    --hash=sha256:22c795ba2832a169ca301cd0a083f7a434e09c538c70beb42782c073651b707d \
+    --hash=sha256:373413d0f82425aaa28fb288009bf0d0964711d347763af2f1b65cafcb028c82 \
+    # via sphinx-ansible-theme
+sphinx==3.2.1 \
+    --hash=sha256:321d6d9b16fa381a5306e5a0b76cd48ffbc588e6340059a729c6fdd66087e0e8 \
+    --hash=sha256:ce6fd7ff5b215af39e2fcd44d4a321f6694b4530b6f2b2109b64d120773faea0 \
+    # via -r requirements.in, myst-parser, sphinx-rtd-theme, sphinxcontrib.programoutput
+sphinxcontrib-applehelp==1.0.2 \
+    --hash=sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a \
+    --hash=sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58 \
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2 \
+    --hash=sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e \
+    --hash=sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4 \
+    # via sphinx
+sphinxcontrib-htmlhelp==1.0.3 \
+    --hash=sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f \
+    --hash=sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b \
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1 \
+    --hash=sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178 \
+    --hash=sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8 \
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3 \
+    --hash=sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72 \
+    --hash=sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6 \
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.4 \
+    --hash=sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc \
+    --hash=sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a \
+    # via sphinx
+sphinxcontrib.programoutput==0.16 \
+    --hash=sha256:0caaa216d0ad8d2cfa90a9a9dba76820e376da6e3152be28d10aedc09f82a3b0 \
+    --hash=sha256:8009d1326b89cd029ee477ce32b45c58d92b8504d48811461c3117014a8f4b1e \
+    # via -r requirements.in
+urllib3==1.25.9 \
+    --hash=sha256:3018294ebefce6572a474f0604c2021e33b3fd8006ecd11d62107a5d2a963527 \
+    --hash=sha256:88206b0eb87e6d677d424843ac5209e3fb9d0190d0ee169599165ec25e9d9115 \
+    # via requests
+
+# WARNING: The following packages were not pinned, but pip requires them to be
+# pinned when the requirements file includes hashes. Consider using the --allow-unsafe flag.
+# pip
+# setuptools
diff --git a/docs/rules.rst b/docs/rules.rst
new file mode 100644
index 0000000..5a02193
--- /dev/null
+++ b/docs/rules.rst
@@ -0,0 +1,13 @@
+.. _lint_rules:
+
+*****
+Rules
+*****
+
+.. contents:: Topics
+
+This topic describes how to use the default Ansible Lint rules, as well as how to create and use custom rules.
+
+.. include:: ../README.rst
+   :start-after: rules-docs-inclusion-marker-do-not-remove
+   :end-before: rules-docs-inclusion-marker-end-do-not-remove
diff --git a/docs/rules_table_generator_ext.py b/docs/rules_table_generator_ext.py
new file mode 100644
index 0000000..51e2f4d
--- /dev/null
+++ b/docs/rules_table_generator_ext.py
@@ -0,0 +1,68 @@
+#! /usr/bin/env python3
+# Requires Python 3.6+
+"""Sphinx extension for generating the rules table document."""
+
+from typing import Dict, List, Union
+
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles, nodes
+
+# isort: split
+
+from docutils import statemachine
+
+from ansiblelint import __version__
+from ansiblelint.constants import DEFAULT_RULESDIR
+from ansiblelint.generate_docs import rules_as_rst
+from ansiblelint.rules import RulesCollection
+
+
+def _nodes_from_rst(
+        state: statemachine.State,
+        rst_source: str,
+) -> List[nodes.Node]:
+    """Turn an RST string into a list of nodes.
+
+    These nodes can be used in the document.
+    """
+    node = nodes.Element()
+    node.document = state.document
+    nested_parse_with_titles(
+        state=state,
+        content=statemachine.ViewList(
+            statemachine.string2lines(rst_source),
+            source='[ansible-lint autogenerated]',
+        ),
+        node=node,
+    )
+    return node.children
+
+
+class AnsibleLintDefaultRulesDirective(SphinxDirective):
+    """Directive ``ansible-lint-default-rules-list`` definition."""
+
+    has_content = False
+
+    def run(self) -> List[nodes.Node]:
+        """Generate a node tree in place of the directive."""
+        self.env.note_reread()  # rebuild the current RST doc unconditionally
+
+        default_rules = RulesCollection([DEFAULT_RULESDIR])
+        rst_rules_table = rules_as_rst(default_rules)
+
+        return _nodes_from_rst(state=self.state, rst_source=rst_rules_table)
+
+
+def setup(app: Sphinx) -> Dict[str, Union[bool, str]]:
+    """Initialize the Sphinx extension."""
+    app.add_directive(
+        'ansible-lint-default-rules-list',
+        AnsibleLintDefaultRulesDirective,
+    )
+
+    return {
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+        'version': __version__,
+    }
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..8fb166e
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,15 @@
+
+.. _using_lint:
+
+
+*****
+Usage
+*****
+
+.. contents:: Topics
+
+This topic describes how to use ``ansible-lint``.
+
+.. include:: ../README.rst
+   :start-after: usage-docs-inclusion-marker-do-not-remove
+   :end-before: usage-docs-inclusion-marker-end-do-not-remove