More docs refactoring (#1173)

Moves configuring and installing into standalone files.
ansible · Dec 30, 2020 · 326e779 · 326e779
1 parent 27567b1
commit 326e779
Show file tree

Hide file tree

Showing 3 changed files with 101 additions and 127 deletions.
diff --git a/README.rst b/README.rst
@@ -36,125 +36,6 @@ only the last two major versions of Ansible.
 
 `Visit the Ansible Lint docs site <https://ansible-lint.readthedocs.io/en/latest/>`_
 
-Installing
-==========
-
-.. installing-docs-inclusion-marker-do-not-remove
-
-Installing on Windows is not supported because we use symlinks inside Python packages.
-
-While our project does not directly ships a container, the
-tool is part of the toolset_ container.  Please avoid raising any bugs
-related to containers and use the discussions_ forum instead.
-
-.. code-block:: bash
-
-    # replace docker with podman
-    docker run -h toolset -it quay.io/ansible/toolset ansible-lint --version
-
-.. _toolset: https://github.com/ansible-community/toolset
-.. _discussions: https://github.com/ansible-community/ansible-lint/discussions
-
-.. note::
-
-    The default installation of ansible-lint package no longer installs any
-    specific version of ansible. You need to either install the desired version
-    of Ansible yourself or mention one of the helper extras:
-
-    * ``core`` - will install latest version of ansible-base 2.10
-    * ``community`` - will install latest version of ansible 2.10 with community collections
-    * ``devel`` - will install Ansible from git devel branch (unsupported)
-
-Using Pip
----------
-
-.. code-block:: bash
-
-    # Assuming you already installed ansible:
-    pip install ansible-lint
-
-    # If you want to install and use latest ansible (w/o community collections)
-    pip install "ansible-lint[core]"
-
-    # If you want to install and use latest ansible with community collections
-    pip install "ansible-lint[community]"
-
-    # If you want to install an older version of Ansible 2.9
-    pip install ansible-lint "ansible>=2.9,<2.10"
-
-.. _installing_from_source:
-
-From Source
------------
-
-**Note**: pip 19.0+ is required for installation. Please consult with the `PyPA User Guide`_
-to learn more about managing Pip versions.
-
-.. code-block:: bash
-
-    pip install git+https://github.com/ansible-community/ansible-lint.git
-
-.. _PyPA User Guide: https://packaging.python.org/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date
-
-.. installing-docs-inclusion-marker-end-do-not-remove
-
-Configuring
-===========
-
-.. configuring-docs-inclusion-marker-do-not-remove
-
-Configuration File
-------------------
-
-Ansible-lint supports local configuration via a ``.ansible-lint`` configuration file. Ansible-lint checks the working directory for the presence of this file and applies any configuration found there. The configuration file location can also be overridden via the ``-c path/to/file`` CLI flag.
-
-If a value is provided on both the command line and via a config file, the values will be merged (if a list like **exclude_paths**), or the **True** value will be preferred, in the case of something like **quiet**.
-
-The following values are supported, and function identically to their CLI counterparts:
-
-.. code-block:: yaml
-
-    exclude_paths:
-      - ./my/excluded/directory/
-      - ./my/other/excluded/directory/
-      - ./last/excluded/directory/
-    parseable: true
-    quiet: true
-    rulesdir:
-      - ./rule/directory/
-    skip_list:
-      - skip_this_tag
-      - and_this_one_too
-      - skip_this_id
-      - '401'
-    tags:
-      - run_this_tag
-    use_default_rules: true
-    verbosity: 1
-    warn_list:
-      - skip_this_tag
-      - and_this_one_too
-      - skip_this_id
-      - '401'
-
-
-Pre-commit Setup
-----------------
-
-To use ansible-lint with `pre-commit`_, just add the following to your local repo's ``.pre-commit-config.yaml`` file. Make sure to change **rev:** to be either a git commit sha or tag of ansible-lint containing ``hooks.yaml``.
-
-.. code-block:: yaml
-
-    - repo: https://github.com/ansible-community/ansible-lint.git
-      rev: v4.1.0
-      hooks:
-        - id: ansible-lint
-          files: \.(yaml|yml)$
-
-.. _pre-commit: https://pre-commit.com
-
-.. configuring-docs-inclusion-marker-end-do-not-remove
-
 Contributing
 ============
 

diff --git a/docs/configuring.rst b/docs/configuring.rst
@@ -7,8 +7,52 @@ Configuring
 
 .. contents:: Topics
 
-This topic describes how to configure Ansible Lint
+Configuration File
+------------------
 
-.. include:: ../README.rst
-   :start-after: configuring-docs-inclusion-marker-do-not-remove
-   :end-before: configuring-docs-inclusion-marker-end-do-not-remove
+Ansible-lint supports local configuration via a ``.ansible-lint`` configuration file. Ansible-lint checks the working directory for the presence of this file and applies any configuration found there. The configuration file location can also be overridden via the ``-c path/to/file`` CLI flag.
+
+If a value is provided on both the command line and via a config file, the values will be merged (if a list like **exclude_paths**), or the **True** value will be preferred, in the case of something like **quiet**.
+
+The following values are supported, and function identically to their CLI counterparts:
+
+.. code-block:: yaml
+
+    exclude_paths:
+      - ./my/excluded/directory/
+      - ./my/other/excluded/directory/
+      - ./last/excluded/directory/
+    parseable: true
+    quiet: true
+    rulesdir:
+      - ./rule/directory/
+    skip_list:
+      - skip_this_tag
+      - and_this_one_too
+      - skip_this_id
+      - '401'
+    tags:
+      - run_this_tag
+    use_default_rules: true
+    verbosity: 1
+    warn_list:
+      - skip_this_tag
+      - and_this_one_too
+      - skip_this_id
+      - '401'
+
+
+Pre-commit Setup
+----------------
+
+To use ansible-lint with `pre-commit`_, just add the following to your local repo's ``.pre-commit-config.yaml`` file. Make sure to change **rev:** to be either a git commit sha or tag of ansible-lint containing ``hooks.yaml``.
+
+.. code-block:: yaml
+
+    - repo: https://github.com/ansible-community/ansible-lint.git
+      rev: v4.1.0
+      hooks:
+        - id: ansible-lint
+          files: \.(yaml|yml)$
+
+.. _pre-commit: https://pre-commit.com
diff --git a/docs/installing.rst b/docs/installing.rst
@@ -8,8 +8,57 @@ Installing
 
 .. contents:: Topics
 
-This topic describes how to install Ansible Lint.
+Installing on Windows is not supported because we use symlinks inside Python packages.
 
-.. include:: ../README.rst
-   :start-after: installing-docs-inclusion-marker-do-not-remove
-   :end-before: installing-docs-inclusion-marker-end-do-not-remove
+While our project does not directly ships a container, the
+tool is part of the toolset_ container.  Please avoid raising any bugs
+related to containers and use the discussions_ forum instead.
+
+.. code-block:: bash
+
+    # replace docker with podman
+    docker run -h toolset -it quay.io/ansible/toolset ansible-lint --version
+
+.. _toolset: https://github.com/ansible-community/toolset
+.. _discussions: https://github.com/ansible-community/ansible-lint/discussions
+
+.. note::
+
+    The default installation of ansible-lint package no longer installs any
+    specific version of ansible. You need to either install the desired version
+    of Ansible yourself or mention one of the helper extras:
+
+    * ``core`` - will install latest version of ansible-base 2.10
+    * ``community`` - will install latest version of ansible 2.10 with community collections
+    * ``devel`` - will install Ansible from git devel branch (unsupported)
+
+Using Pip
+---------
+
+.. code-block:: bash
+
+    # Assuming you already installed ansible:
+    pip install ansible-lint
+
+    # If you want to install and use latest ansible (w/o community collections)
+    pip install "ansible-lint[core]"
+
+    # If you want to install and use latest ansible with community collections
+    pip install "ansible-lint[community]"
+
+    # If you want to install an older version of Ansible 2.9
+    pip install ansible-lint "ansible>=2.9,<2.10"
+
+.. _installing_from_source:
+
+From Source
+-----------
+
+**Note**: pip 19.0+ is required for installation. Please consult with the `PyPA User Guide`_
+to learn more about managing Pip versions.
+
+.. code-block:: bash
+
+    pip install git+https://github.com/ansible-community/ansible-lint.git
+
+.. _PyPA User Guide: https://packaging.python.org/tutorials/installing-packages/#ensure-pip-setuptools-and-wheel-are-up-to-date