testing_sanity.rst: improvement (#2441)

* testing_sanity.rst: improvement

* Add collection specific remarks

* Change suggested

Author: Andersson007

docs/docsite/rst/dev_guide/testing_sanity.rst

@@ -14,39 +14,50 @@ The primary purpose of these tests is to enforce Ansible coding standards and re
 Tests are run with ``ansible-test sanity``.
 All available tests are run unless the ``--test`` option is used.
 
+.. _set_up_env_to_run_tests:
+
+Set up your environment
+=======================
+
+1. :ref:`Install ansible-core<installation_guide>` that provides the ``ansible-test`` tool.
+
+  * If you want to run checks available in the development version of ``ansible-core``, :ref:`install it from source code<from_source>`.
+
+    * Run ``source hacking/env-setup`` from its source code directory in the same terminal session you run your tests.
+
+2. Install ``podman`` or ``docker`` to avoid installing all the dependencies on your system.
+3. If you test files in a collection:
+
+  * Ensure you have your collection installed in the following path in your home directory: ``~/ansible_collections/<NAMESPACE>/<COLLECTION_NAME>``. For instance, in case of the ``community.general`` collection, it will be ``~/ansible_collections/community/general``
+  * If your collection is hosted on a remote server such as GitHub, clone it to that path as follows: ``git clone <COLLECTION_REPO_URL> ~/ansible_collections/<NAMESPACE>/<COLLECTION_NAME>``
 
 How to run
 ==========
 
 .. note::
-   To run sanity tests using docker, always use the default docker image
-   by passing the ``--docker`` or ``--docker default`` argument.
+   To run sanity tests using podman or docker, always use the default docker image
+   by passing the ``--docker`` argument without specifying the image name.
+
+
+1. When testing files in a collection, change your location to your collection directory you created while :ref:`setting up your environment<set_up_env_to_run_tests>`:
 
 .. code:: shell
 
-   source hacking/env-setup
+   cd ~/ansible_collections/<NAMESPACE>/<COLLECTION_NAME>
 
-   # Run all sanity tests
-   ansible-test sanity
+2. To run all sanity tests in a container:
 
-   # Run all sanity tests including disabled ones
-   ansible-test sanity --allow-disabled
+.. code:: shell
 
-   # Run all sanity tests against certain file(s)
-   ansible-test sanity lib/ansible/modules/files/template.py
-   
-   # Run all sanity tests against certain folder(s)
-   ansible-test sanity lib/ansible/modules/files/
+   ansible-test sanity --docker
 
-   # Run all tests inside docker (good if you don't have dependencies installed)
-   ansible-test sanity --docker default
+* To run a :ref:`specific test<all_sanity_tests>`, add the ``--test <NAME>`` argument, for example, ``--test validate-modules``.
 
-   # Run validate-modules against a specific file
-   ansible-test sanity --test validate-modules lib/ansible/modules/files/template.py
+  * To list available tests, run: ``ansible-test sanity --list-tests``
+
+* To include disabled tests, add the ``--allow-disabled`` argument.
 
 Available Tests
 ===============
 
-Tests can be listed with ``ansible-test sanity --list-tests``.
-
-See the full list of :ref:`sanity tests <all_sanity_tests>`, which details the various tests and details how to fix identified issues.
+See the full list of :ref:`sanity tests <all_sanity_tests>`, which also details how to fix identified issues.