[doc] Cleanup the installation/testing/badge documentation in the Readme

10 files changed, 229 insertions, 176 deletions

diff --git a/README.rst b/README.rst
index d951f7a70..835283199 100644
--- a/README.rst
+++ b/README.rst
@@ -18,6 +18,9 @@ Pylint
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/ambv/black
 
+.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
+    :target: https://github.com/PyCQA/pylint
+
 .. image:: https://results.pre-commit.ci/badge/github/PyCQA/pylint/main.svg
    :target: https://results.pre-commit.ci/latest/github/PyCQA/pylint/main
    :alt: pre-commit.ci status
@@ -26,25 +29,6 @@ Pylint
    :width: 200
    :alt: Tidelift
 
-.. list-table::
-   :widths: 10 100
-
-   * - |tideliftlogo|
-     - Professional support for pylint is available as part of the `Tidelift
-       Subscription`_.  Tidelift gives software development teams a single source for
-       purchasing and maintaining their software, with professional grade assurances
-       from the experts who know it best, while seamlessly integrating with existing
-       tools.
-
-.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme
-
-Documentation
-=============
-
-Please check `the full documentation`_.
-
-.. _`the full documentation`: https://pylint.pycqa.org/
-
 What is pylint ?
 ================
 
@@ -73,67 +57,50 @@ re-evaluate and re-enable messages as your priorities evolve.
 
 Pylint ships with three additional tools:
 
-- :ref:`pyreverse <pyreverse>` (standalone tool that generates package and class diagrams.)
-- :ref:`symilar <symilar>`  (duplicate code finder that is also integrated in pylint)
-- :ref:`epylint <pylint_in_flymake>` (Emacs and Flymake compatible Pylint)
-
-Install
--------
-
-Pylint can be simply installed by running::
-
-    pip install pylint
-
-If you are using Python 3.7.2+, upgrade to get full support for your version::
-
-    pip install pylint --upgrade
-
-If you want to install from a source distribution, extract the tarball and run
-the following command ::
+- pyreverse_ (standalone tool that generates package and class diagrams.)
+- symilar_  (duplicate code finder that is also integrated in pylint)
+- epylint_ (Emacs and Flymake compatible Pylint)
 
-    python setup.py install
+.. Enf of do not modify this without also modifying doc/index.rst
 
+.. _pyreverse: https://pylint.pycqa.org/en/latest/pyreverse.html
+.. _symilar: https://pylint.pycqa.org/en/latest/symilar.html
+.. _epylint: https://pylint.pycqa.org/en/latest/user_guide/ide_integration/flymake-emacs.html
 
-Do make sure to do the same for astroid, which is used internally by pylint.
+Install
+-------
 
-For debian and rpm packages, use your usual tools according to your Linux distribution.
+.. Do not modify anything here, modify doc/user_guide/installation.rst instead
 
-More information about installation and available distribution format
-can be found here_.
+For command line use, pylint is installed with::
 
-Testing
--------
+    pip install pylint
 
-You should be able to install our tests dependencies with::
+It can also be integrated in most editors or IDE. More information can be found
+`in the documentation`_.
 
-    pip install -r requirements_test.txt
+.. _in the documentation: https://pylint.pycqa.org/en/latest/user_guide/installation.html
 
-You can then use pytest_ directly. If you want to run tests on a specific portion of the
-code with pytest_ and your local python version::
+Documentation
+=============
 
-    # ( pip install pytest-cov )
-    python3 -m pytest
-    # Everything in tests/message with coverage for the relevant code:
-    python3 -m pytest tests/message/ --cov=pylint.message
-    coverage html
-    # Only the functional test "missing_kwoa_py3":
-    python3 -m pytest "tests/test_functional.py::test_functional[missing_kwoa_py3]"
+Please check `the full documentation`_.
 
-You can also *optionally* install tox_. To run the test suite for a particular
-Python version, with tox you can do::
+.. _`the full documentation`: https://pylint.pycqa.org/
 
-    tox -e py39
+Contributing
+------------
 
-To run individual tests with ``tox``, you can do::
+We welcome all contributions, doc, code, checking issues for duplicate or telling us
+that we can close them, confirming that it's still an issue, creating issues because
+you found a bug or want a feature... everything helps !
 
-    tox -e py37 -- -k name_of_the_test
+Please follow the `code of conduct`_ and check `the contribution documentation`_ if you want to
+make a code contribution.
 
-If you're testing new changes in astroid you need to clone astroid_ and install
-with an editable installation as follows::
+.. _code of conduct: https://github.com/Pierre-Sassoulas/pylint/blob/main/CODE_OF_CONDUCT.md
+.. _the contribution documentation: https://pylint.pycqa.org/en/latest/development_guide/contribute.html
 
-    git clone https://github.com/PyCQA/astroid.git
-    cd astroid
-    python3 -m pip install -e .
 
 Show your usage
 -----------------
@@ -143,27 +110,9 @@ You can place this badge in your README to let others know your project uses pyl
     .. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
         :target: https://github.com/PyCQA/pylint
 
-Use the badge in your project's README.md (or any other Markdown file)::
-
-    [![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/PyCQA/pylint)
-
-Use the badge in your project's README.rst (or any other rst file)::
-
-    .. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
-        :target: https://github.com/PyCQA/pylint
-
-
-If you use GitHub Actions, and one of your CI workflows begins with "name: pylint", you
-can use GitHub's `workflow status badges <https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge#using-the-workflow-file-name>`_
-to show an up-to-date indication of whether pushes to your default branch pass pylint.
-For more detailed information, check the documentation.
+See how in `the badge documentation`_.
 
-.. _here: https://pylint.pycqa.org/en/latest/user_guide/installation.html
-.. _tox: https://tox.readthedocs.io/en/latest/
-.. _pytest: https://docs.pytest.org/en/latest/
-.. _pytest-benchmark: https://pytest-benchmark.readthedocs.io/en/latest/index.html
-.. _pytest-cov: https://pypi.org/project/pytest-cov/
-.. _astroid: https://github.com/PyCQA/astroid
+.. _the badge documentation: https://pylint.pycqa.org/en/latest/user_guide/badge.html
 
 License
 -------
@@ -174,3 +123,18 @@ The icon files are licensed under the `CC BY-SA 4.0 <https://creativecommons.org
 
 - `doc/logo.png <https://raw.githubusercontent.com/PyCQA/pylint/main/doc/logo.png>`_
 - `doc/logo.svg <https://raw.githubusercontent.com/PyCQA/pylint/main/doc/logo.svg>`_
+
+Support
+-------
+
+.. list-table::
+   :widths: 10 100
+
+   * - |tideliftlogo|
+     - Professional support for pylint is available as part of the `Tidelift
+       Subscription`_.  Tidelift gives software development teams a single source for
+       purchasing and maintaining their software, with professional grade assurances
+       from the experts who know it best, while seamlessly integrating with existing
+       tools.
+
+.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme
diff --git a/doc/conf.py b/doc/conf.py
index 3ba256dcb..78b55f3f6 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -62,6 +62,7 @@ redirects: dict[str, str] = {
     "messages/messages_list": "../user_guide/messages/messages_overview.html",
     "user_guide/message-control": "messages/message_control.html",
     "technical_reference/c_extensions": "../user_guide/c_extensions.html",
+    "development/testing": "tests/index.html",
 }
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/development_guide/contribute.rst b/doc/development_guide/contribute.rst
index 015a2bd95..328f86b1b 100644
--- a/doc/development_guide/contribute.rst
+++ b/doc/development_guide/contribute.rst
@@ -4,8 +4,6 @@
  Contributing
 ==============
 
-Pull requests are amazing and most welcome !
-
 .. _repository:
 
 Repository
diff --git a/doc/development_guide/index.rst b/doc/development_guide/index.rst
index 4e61de0cb..9eefc992c 100644
--- a/doc/development_guide/index.rst
+++ b/doc/development_guide/index.rst
@@ -1,4 +1,3 @@
-
 Development
 ===========
 
@@ -7,6 +6,6 @@ Development
    :titlesonly:
 
    contribute
-   testing
+   tests/index
    api/index
    profiling
diff --git a/doc/development_guide/tests/index.rst b/doc/development_guide/tests/index.rst
new file mode 100644
index 000000000..b612ccea2
--- /dev/null
+++ b/doc/development_guide/tests/index.rst
@@ -0,0 +1,18 @@
+.. _testing:
+
+=======
+Testing
+=======
+
+.. _test_your_code:
+
+Pylint is very well tested and has a high code coverage. New contributions are not accepted
+unless they include tests.
+
+.. toctree::
+   :maxdepth: 3
+   :titlesonly:
+
+   install
+   launching_test
+   writting_test
diff --git a/doc/development_guide/tests/install.rst b/doc/development_guide/tests/install.rst
new file mode 100644
index 000000000..c52301ce3
--- /dev/null
+++ b/doc/development_guide/tests/install.rst
@@ -0,0 +1,25 @@
+Installation
+============
+
+Before you start testing your code, you need to install your source-code package locally.
+Suppose you have cloned pylint into a directory, say ``my-pylint``.
+To set up your environment for testing, open a terminal and run::
+
+    cd my-pylint
+    pip install -r requirements_test_min.txt
+
+This ensures your testing environment is similar to Pylint's testing environment on GitHub.
+
+If you're testing new changes in astroid you need to clone astroid_ and install
+with an editable installation as follows::
+
+    git clone https://github.com/PyCQA/astroid.git
+    cd astroid
+    python3 -m pip install -e .
+
+If you want to check the coverage locally, consider using `pytest-cov`_::
+
+    python3 -m pip install pytest-cov
+
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _astroid: https://github.com/pycqa/astroid
diff --git a/doc/development_guide/tests/launching_test.rst b/doc/development_guide/tests/launching_test.rst
new file mode 100644
index 000000000..c4b014d98
--- /dev/null
+++ b/doc/development_guide/tests/launching_test.rst
@@ -0,0 +1,82 @@
+Launching tests
+===============
+
+pytest
+------
+
+Since we use pytest_ to run the tests, you can also use it on its own.
+We do recommend using the tox_ command though::
+
+    pytest pylint -k test_functional
+
+You can use pytest_ directly. If you want to run tests on a specific portion of the
+code with pytest_ and your local python version::
+
+    python3 -m pytest
+
+
+Everything in tests/message with coverage for the relevant code (require `pytest-cov`_)::
+
+    python3 -m pytest tests/message/ --cov=pylint.message
+    coverage html
+
+Only the functional test "missing_kwoa_py3"::
+
+    python3 -m pytest "tests/test_functional.py::test_functional[missing_kwoa_py3]"
+
+tox
+---
+
+You can also *optionally* install tox_ and run our tests using the tox_ package, as in::
+
+    python -m tox
+    python -m tox -epy38 # for Python 3.8 suite only
+    python -m tox -epylint # for running Pylint over Pylint's codebase
+    python -m tox -eformatting # for running formatting checks over Pylint's codebase
+
+It's usually a good idea to run tox_ with ``--recreate``. This flag tells tox_ to re-download
+all dependencies before running the tests. This can be important when a new version of
+astroid_ or any of the other dependencies has been published::
+
+    python -m tox --recreate # The entire tox environment will be recreated
+    python -m tox --recreate -e py310 # The python 3.10 tox environment will be recreated
+
+
+To run only a specific test suite, use a pattern for the test filename
+(**without** the ``.py`` extension), as in::
+
+    python -m tox -e py310 -- -k test_functional
+    python -m tox -e py310 -- -k  \*func\*
+    python -m tox --recreate -e py310 -- -k test_functional # With recreation of the environment
+
+
+.. _primer_tests:
+
+Primer tests
+------------
+
+Pylint also uses what we refer to as ``primer`` tests. These are tests that are run automatically
+in our Continuous Integration and check whether any changes in Pylint lead to crashes or fatal errors
+on the ``stdlib`` and a selection of external repositories.
+
+To run the ``primer`` tests you can add either ``--primer-stdlib`` or ``--primer-external`` to the
+pytest_ command. If you want to only run the ``primer`` you can add either of their marks, for example::
+
+    pytest -m primer_stdlib --primer-stdlib
+
+The external ``primer`` has been split up in two marks to speed up our Continuous Integration. You can run
+either of the two batches or run them both::
+
+    pytest -m primer_external_batch_one --primer-external # Runs batch one
+    pytest -m primer_external_batch_two --primer-external # Runs batch two
+    pytest -m "primer_external_batch_one or primer_external_batch_two" --primer-external # Runs both batches
+
+The list of repositories is created on the basis of three criteria: 1) projects need to use a diverse
+range of language features, 2) projects need to be well maintained and 3) projects should not have a codebase
+that is too repetitive. This guarantees a good balance between speed of our CI and finding potential bugs.
+
+You can find the latest list of repositories and any relevant code for these tests in the ``tests/primer``
+directory.
+
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _astroid: https://github.com/pycqa/astroid
diff --git a/doc/development_guide/testing.rst b/doc/development_guide/tests/writting_test.rst
index 0bf7474af..2d9844b16 100644
--- a/doc/development_guide/testing.rst
+++ b/doc/development_guide/tests/writting_test.rst
@@ -1,65 +1,38 @@
-.. -*- coding: utf-8 -*-
-.. _testing:
+.. _writing_tests:
 
-==============
- Testing
-==============
+Writing tests
+=============
 
-.. _test_your_code:
+Pylint uses three types of tests: unittests, functional tests and primer tests.
 
-Test your code!
-----------------
-
-Pylint is very well tested and has a high code coverage. New contributions are not accepted
-unless they include tests.
-
-Before you start testing your code, you need to install your source-code package locally.
-Suppose you have cloned pylint into a directory, say ``my-pylint``.
-To set up your environment for testing, open a terminal and run:
-
-    cd my-pylint
-    pip install -r requirements_test_min.txt
-
-This ensures your testing environment is similar to Pylint's testing environment on GitHub.
-
-Pylint uses two types of tests: unittests and functional tests.
-
-  - The unittests can be found in the ``/pylint/test`` directory and they can
-    be used for testing almost anything Pylint related.
-
-  - The functional tests can be found in the ``/pylint/test/functional`` directory. They are
-    mainly used to test whether Pylint emits the correct messages.
+- :ref:`unittests <writing_unittests>` can be found in ``pylint/tests``. Unless you're working on pylint's
+  internal you're probably not going to have to write any.
+- :ref:`Global functional tests <writing_functional_tests>`  can be found in the ``pylint/tests/functional``. They are
+  mainly used to test whether Pylint emits the correct messages.
+- :ref:`Configuration's functional tests <writing_config_functional_tests>`  can be found in the
+  ``pylint/tests/config/functional``. They are used to test Pylint's configuration loading.
+- :ref:`Primer tests <primer_tests>` you can suggest a new external repository to check but there's nothing to do
+  most of the time.
 
-Before writing a new test it is often a good idea to ensure that your change isn't
-breaking a current test. You can run our tests using the tox_ package, as in::
+.. _writing_unittests:
 
-    python -m tox
-    python -m tox -epy38 # for Python 3.8 suite only
-    python -m tox -epylint # for running Pylint over Pylint's codebase
-    python -m tox -eformatting # for running formatting checks over Pylint's codebase
-
-It's usually a good idea to run tox_ with ``--recreate``. This flag tells tox_ to redownload
-all dependencies before running the tests. This can be important when a new version of
-astroid_ or any of the other dependencies has been published::
-
-    python -m tox --recreate # The entire tox environment will be recreated
-    python -m tox --recreate -e py310 # The python 3.10 tox environment will be recreated
+Unittest tests
+--------------
 
+Most other tests reside in the '/pylint/test' directory. These unittests can be used to test
+almost all functionality within Pylint. A good step before writing any new unittests is to look
+at some tests that test a similar funcitionality. This can often help write new tests.
 
-To run only a specific test suite, use a pattern for the test filename
-(**without** the ``.py`` extension), as in::
+If your new test requires any additional files you can put those in the
+``/pylint/test/regrtest_data`` directory. This is the directory we use to store any data needed for
+the unittests.
 
-    python -m tox -e py310 -- -k test_functional
-    python -m tox -e py310 -- -k  \*func\*
-    python -m tox --recreate -e py310 -- -k test_functional # With recreation of the environment
 
-Since we use pytest_ to run the tests, you can also use it on its own.
-We do recommend using the tox_ command though::
 
-    pytest pylint -k test_functional
+.. _writing_functional_tests:
 
-Writing functional tests
-------------------------
+Functional tests
+----------------
 
 These are residing under ``/pylint/test/functional`` and they are formed of multiple
 components. First, each Python file is considered to be a test case and it
@@ -123,20 +96,11 @@ on the the current output by appending ``--update-functional-output`` to the com
 
     python tests/test_functional.py --update-functional-output -k "test_functional[len_checks]"
 
-Writing unittest tests
-------------------------
-
-Most other tests reside in the '/pylint/test' directory. These unittests can be used to test
-almost all functionality within Pylint. A good step before writing any new unittests is to look
-at some tests that test a similar funcitionality. This can often help write new tests.
-
-If your new test requires any additional files you can put those in the
-``/pylint/test/regrtest_data`` directory. This is the directory we use to store any data needed for
-the unittests.
 
+.. _writing_config_functional_tests:
 
-Writing functional tests for configurations
--------------------------------------------
+Functional tests for configurations
+-----------------------------------
 
 To test the different ways to configure Pylint there is also a small functional test framework
 for configuration files. These tests can be found in the '/pylint/test/config' directory.
@@ -168,32 +132,8 @@ and should exit with exit code 2 the ``.out`` file should be named ``bad_configu
 The content of the ``.out`` file should have a similar pattern as a normal Pylint output. Note that the
 module name should be ``{abspath}`` and the file name ``{relpath}``.
 
-Primer tests
--------------------------------------------
-
-Pylint also uses what we refer to as ``primer`` tests. These are tests that are run automatically
-in our Continuous Integration and check whether any changes in Pylint lead to crashes or fatal errors
-on the ``stdlib`` and a selection of external repositories.
-
-To run the ``primer`` tests you can add either ``--primer-stdlib`` or ``--primer-external`` to the
-pytest_ command. If you want to only run the ``primer`` you can add either of their marks, for example::
-
-    pytest -m primer_stdlib --primer-stdlib
-
-The external ``primer`` has been split up in two marks to speed up our Continuous Integration. You can run
-either of the two batches or run them both::
-
-    pytest -m primer_external_batch_one --primer-external # Runs batch one
-    pytest -m primer_external_batch_two --primer-external # Runs batch two
-    pytest -m "primer_external_batch_one or primer_external_batch_two" --primer-external # Runs both batches
-
-The list of repositories is created on the basis of three criteria: 1) projects need to use a diverse
-range of language features, 2) projects need to be well maintained and 3) projects should not have a codebase
-that is too repetitive. This guarantees a good balance between speed of our CI and finding potential bugs.
-
-You can find the latest list of repositories and any relevant code for these tests in the ``tests/primer``
-directory.
 
 .. _tox: https://tox.wiki/en/latest/
 .. _pytest: https://docs.pytest.org/en/latest/
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _astroid: https://github.com/pycqa/astroid
diff --git a/doc/user_guide/badge.rst b/doc/user_guide/badge.rst
new file mode 100644
index 000000000..8463d40b3
--- /dev/null
+++ b/doc/user_guide/badge.rst
@@ -0,0 +1,25 @@
+
+.. _badge:
+
+Show your usage
+---------------
+
+You can place this badge in your README to let others know your project uses pylint.
+
+    .. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
+        :target: https://github.com/PyCQA/pylint
+
+Use the badge in your project's README.md (or any other Markdown file)::
+
+    [![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/PyCQA/pylint)
+
+Use the badge in your project's README.rst (or any other rst file)::
+
+    .. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
+        :target: https://github.com/PyCQA/pylint
+
+
+If you use GitHub Actions, and one of your CI workflows begins with "name: pylint", you
+can use GitHub's `workflow status badges <https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge#using-the-workflow-file-name>`_
+to show an up-to-date indication of whether pushes to your default branch pass pylint.
+For more detailed information, check the documentation.
diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst
index 0a17337f9..46fecbe54 100644
--- a/doc/user_guide/index.rst
+++ b/doc/user_guide/index.rst
@@ -14,3 +14,4 @@ User Guide
    options
    ide_integration/ide-integration
    pre-commit-integration
+   badge