Reorganize the documentation table of content (#6589)

* [doc] Reorganize the doc table of content with four levels

User, developer, contributor, maintainer.

Co-authored-by: Jacob Walls <jacobtylerwalls@gmail.com>

38 files changed, 196 insertions, 111 deletions

diff --git a/doc/conf.py b/doc/conf.py
index da618cf25..c3ff32d1c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -43,6 +43,7 @@ extensions = [
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx_reredirects",
+    "myst_parser",
 ]
 
 
@@ -54,18 +55,44 @@ extensions = [
 # https://readthedocs.org/dashboard/pylint/redirects/
 redirects: dict[str, str] = {
     # "<source>": "<target>"
-    "intro": "index.html",
-    "support": "contact.html",
-    "user_guide/ide-integration": "installation.html",
     "additional_commands/index": "../index.html",
+    "development_guide/index": "api/index.html",
+    "development_guide/contribute": "../development_guide/contributor_guide/index.html",
+    "development_guide/contributor_guide": "contributor_guide/index.html",
+    "development_guide/profiling": "../development_guide/contributor_guide/profiling.html",
+    "development_guide/tests/index": "../contributor_guide/tests/index.html",
+    "development_guide/tests/install": "../contributor_guide/tests/install.html",
+    "development_guide/tests/launching_test": "../contributor_guide/tests/launching_test.html",
+    # There was a typo in the original file, don't fix.
+    "development_guide/tests/writting_test": "../contributor_guide/tests/writing_test.html",
+    "development/testing": "tests/index.html",
+    "how_tos/custom_checkers": "../development_guide/how_tos/custom_checkers.html",
+    "how_tos/index": "../development_guide/how_tos/index.html",
+    "how_tos/plugins": "../development_guide/how_tos/plugins.html",
+    "how_tos/transform_plugins": "../development_guide/how_tos/transform_plugins.html",
+    "intro": "index.html",
     "messages/messages_introduction": "../user_guide/messages/index.html",
     "messages/messages_list": "../user_guide/messages/messages_overview.html",
-    "user_guide/message-control": "messages/message_control.html",
+    "support": "contact.html",
     "technical_reference/c_extensions": "../user_guide/messages/error/no-member.html",
+    "technical_reference/checkers": "../development_guide/technical_reference/checkers.html",
+    "technical_reference/features": "../user_guide/checkers/features.html",
+    "technical_reference/index": "../development_guide/technical_reference/index.html",
+    "technical_reference/startup": "../development_guide/technical_reference/startup.html",
     "user_guide/configuration/naming-styles": "../user_guide/messages/convention/invalid-name.html",
-    "development/testing": "tests/index.html",
+    "user_guide/ide_integration/flymake-emacs": "../installation/ide_integration/flymake-emacs.html",
+    "user_guide/ide_integration/ide-integration": "../installation/ide_integration/index.html",
+    "user_guide/ide-integration": "installation.html",
+    "user_guide/ide_integration/textmate": "../installation/ide_integration/textmate.html",
+    "user_guide/index": "installation/index.html",
+    "user_guide/message-control": "messages/message_control.html",
+    "user_guide/options": "configuration/all-options.html",
+    "user_guide/output": "usage/output.html",
+    "user_guide/pre-commit-integration": "installation/pre-commit-integration.html",
+    "user_guide/run": "usage/run.html",
 }
 
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
diff --git a/doc/development_guide/contribute.rst b/doc/development_guide/contributor_guide/contribute.rst
index b09414a12..b09414a12 100644
--- a/doc/development_guide/contribute.rst
+++ b/doc/development_guide/contributor_guide/contribute.rst
diff --git a/doc/development_guide/contributor_guide/index.rst b/doc/development_guide/contributor_guide/index.rst
new file mode 100644
index 000000000..8becbe3a6
--- /dev/null
+++ b/doc/development_guide/contributor_guide/index.rst
@@ -0,0 +1,13 @@
+Contributing to pylint
+======================
+
+The contributor guide will help you if you want to contribute to pylint itself.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   contribute
+   tests/index
+   profiling
+   release
diff --git a/doc/development_guide/profiling.rst b/doc/development_guide/contributor_guide/profiling.rst
index bb49038ff..bb49038ff 100644
--- a/doc/development_guide/profiling.rst
+++ b/doc/development_guide/contributor_guide/profiling.rst
diff --git a/doc/release.md b/doc/development_guide/contributor_guide/release.md
index 6953e7e3d..6953e7e3d 100644
--- a/doc/release.md
+++ b/doc/development_guide/contributor_guide/release.md
diff --git a/doc/development_guide/tests/index.rst b/doc/development_guide/contributor_guide/tests/index.rst
index b612ccea2..2b069857b 100644
--- a/doc/development_guide/tests/index.rst
+++ b/doc/development_guide/contributor_guide/tests/index.rst
@@ -15,4 +15,4 @@ unless they include tests.
 
    install
    launching_test
-   writting_test
+   writing_test
diff --git a/doc/development_guide/tests/install.rst b/doc/development_guide/contributor_guide/tests/install.rst
index c52301ce3..c52301ce3 100644
--- a/doc/development_guide/tests/install.rst
+++ b/doc/development_guide/contributor_guide/tests/install.rst
diff --git a/doc/development_guide/tests/launching_test.rst b/doc/development_guide/contributor_guide/tests/launching_test.rst
index c4b014d98..c4b014d98 100644
--- a/doc/development_guide/tests/launching_test.rst
+++ b/doc/development_guide/contributor_guide/tests/launching_test.rst
diff --git a/doc/development_guide/tests/writting_test.rst b/doc/development_guide/contributor_guide/tests/writing_test.rst
index 2d9844b16..2d9844b16 100644
--- a/doc/development_guide/tests/writting_test.rst
+++ b/doc/development_guide/contributor_guide/tests/writing_test.rst
diff --git a/doc/how_tos/custom_checkers.rst b/doc/development_guide/how_tos/custom_checkers.rst
index eff8cf543..eff8cf543 100644
--- a/doc/how_tos/custom_checkers.rst
+++ b/doc/development_guide/how_tos/custom_checkers.rst
diff --git a/doc/how_tos/index.rst b/doc/development_guide/how_tos/index.rst
index 7ec3a2f36..7ec3a2f36 100644
--- a/doc/how_tos/index.rst
+++ b/doc/development_guide/how_tos/index.rst
diff --git a/doc/how_tos/plugins.rst b/doc/development_guide/how_tos/plugins.rst
index bc2c0f14c..bc2c0f14c 100644
--- a/doc/how_tos/plugins.rst
+++ b/doc/development_guide/how_tos/plugins.rst
diff --git a/doc/how_tos/transform_plugins.rst b/doc/development_guide/how_tos/transform_plugins.rst
index 031faa0f1..031faa0f1 100644
--- a/doc/how_tos/transform_plugins.rst
+++ b/doc/development_guide/how_tos/transform_plugins.rst
diff --git a/doc/development_guide/index.rst b/doc/development_guide/index.rst
deleted file mode 100644
index 9eefc992c..000000000
--- a/doc/development_guide/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-Development
-===========
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   contribute
-   tests/index
-   api/index
-   profiling
diff --git a/doc/technical_reference/checkers.rst b/doc/development_guide/technical_reference/checkers.rst
index de703ac05..de703ac05 100644
--- a/doc/technical_reference/checkers.rst
+++ b/doc/development_guide/technical_reference/checkers.rst
diff --git a/doc/technical_reference/index.rst b/doc/development_guide/technical_reference/index.rst
index 1d38f4701..9ec307902 100644
--- a/doc/technical_reference/index.rst
+++ b/doc/development_guide/technical_reference/index.rst
@@ -14,5 +14,3 @@ Technical Reference
 
   startup
   checkers
-  extensions
-  features
diff --git a/doc/technical_reference/startup.rst b/doc/development_guide/technical_reference/startup.rst
index 22a395ad3..22a395ad3 100644
--- a/doc/technical_reference/startup.rst
+++ b/doc/development_guide/technical_reference/startup.rst
diff --git a/doc/exts/pylint_extensions.py b/doc/exts/pylint_extensions.py
index 15511a662..ce10fa637 100755
--- a/doc/exts/pylint_extensions.py
+++ b/doc/exts/pylint_extensions.py
@@ -47,12 +47,10 @@ def builder_inited(app: Optional[Sphinx]) -> None:
     linter.load_plugin_modules(modules)
 
     extensions_doc = os.path.join(
-        base_path, "doc", "technical_reference", "extensions.rst"
+        base_path, "doc", "user_guide", "checkers", "extensions.rst"
     )
     with open(extensions_doc, "w", encoding="utf-8") as stream:
-        stream.write(
-            get_rst_title("Optional Pylint checkers in the extensions module", "=")
-        )
+        stream.write(get_rst_title("Optional checkers", "="))
         stream.write("Pylint provides the following optional plugins:\n\n")
         for module in modules:
             stream.write(f"- :ref:`{module}`\n")
diff --git a/doc/exts/pylint_features.py b/doc/exts/pylint_features.py
index 097577c29..9faac95bd 100755
--- a/doc/exts/pylint_features.py
+++ b/doc/exts/pylint_features.py
@@ -26,7 +26,7 @@ def builder_inited(app: Optional[Sphinx]) -> None:
     )
     linter = PyLinter()
     linter.load_default_plugins()
-    features = os.path.join(base_path, "doc", "technical_reference", "features.rst")
+    features = os.path.join(base_path, "doc", "user_guide", "checkers", "features.rst")
     with open(features, "w", encoding="utf-8") as stream:
         stream.write("Pylint features\n")
         stream.write("===============\n\n")
diff --git a/doc/exts/pylint_options.py b/doc/exts/pylint_options.py
index 4a6e743ef..e6bd60b43 100644
--- a/doc/exts/pylint_options.py
+++ b/doc/exts/pylint_options.py
@@ -150,7 +150,6 @@ def _write_options_page(options: OptionsDataDict, linter: PyLinter) -> None:
     ) as stream:
         stream.write(
             f"""
-{get_rst_title("All pylint options", "=")}
 
 {sections_string}
 """
diff --git a/doc/faq.rst b/doc/faq.rst
index 66856daf9..ea20e6731 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -147,7 +147,7 @@ Alternatively, if you use ``pyproject.toml``, e.g.
     ]
 
 See also the :ref:`exhaustive list of possible options
-<user_guide/configuration/all-options:all pylint options>`.
+<all-configurations-options>`.
 
 4.7 Why are there a bunch of messages disabled by default?
 ----------------------------------------------------------
@@ -157,7 +157,7 @@ they are prone to false positives or that they are opinionated enough
 for not being included as default messages.
 
 You can see the plugin you need to explicitly :ref:`load in the technical reference
-<technical_reference/extensions:optional pylint checkers in the extensions module>`.
+<user_guide/checkers/extensions:optional checkers>`.
 
 4.8 I am using another popular linter alongside pylint. Which messages should I disable to avoid duplicates?
 ------------------------------------------------------------------------------------------------------------
diff --git a/doc/index.rst b/doc/index.rst
index 89110b02b..806ede7d6 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,12 +6,48 @@
    :hidden:
 
    tutorial
-   user_guide/index.rst
-   how_tos/index.rst
-   technical_reference/index.rst
-   development_guide/index.rst
+
+.. toctree::
+   :caption: User Guide
+   :titlesonly:
+   :hidden:
+
+   user_guide/installation/index
+   user_guide/usage/index
+   user_guide/messages/index
+   user_guide/configuration/index
+   user_guide/checkers/index
+
+.. toctree::
+   :caption: Developer Guide
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   development_guide/api/index
+   development_guide/how_tos/index.rst
+   development_guide/technical_reference/index.rst
+   development_guide/contributor_guide/index
+
+.. toctree::
+   :caption: Additional tools
+   :titlesonly:
+   :hidden:
+
    pyreverse
    symilar
+
+.. toctree::
+   :caption: Changelog
+   :titlesonly:
+   :hidden:
+
+   whatsnew/index.rst
+
+.. toctree::
+   :caption: Support
+   :titlesonly:
+   :hidden:
+
    faq
    contact
-   whatsnew/index.rst
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 3fb58817a..bc91aeb63 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,4 +1,5 @@
 Sphinx==4.5.0
 sphinx-reredirects<1
+myst-parser~=0.16
 furo==2022.4.7
 -e .
diff --git a/doc/user_guide/checkers/index.rst b/doc/user_guide/checkers/index.rst
new file mode 100644
index 000000000..296178182
--- /dev/null
+++ b/doc/user_guide/checkers/index.rst
@@ -0,0 +1,10 @@
+Checkers
+========
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   features
+   extensions
diff --git a/doc/user_guide/configuration/index.rst b/doc/user_guide/configuration/index.rst
new file mode 100644
index 000000000..d0d8b695b
--- /dev/null
+++ b/doc/user_guide/configuration/index.rst
@@ -0,0 +1,14 @@
+.. _all-configurations-options:
+
+=============
+Configuration
+=============
+
+Pylint is highly configurable. There are a lot of options to follow the needs of
+various projects and a lot of checks to activate if they suit your style.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   all-options
diff --git a/doc/user_guide/ide_integration/ide-integration.rst b/doc/user_guide/ide_integration/ide-integration.rst
deleted file mode 100644
index dea1106d0..000000000
--- a/doc/user_guide/ide_integration/ide-integration.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-###########################
- Editor and IDE integration
-###########################
-Pylint can be integrated in various editors and IDE's. Below you can find tutorials for some of the most common ones.
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   flymake-emacs.rst
-   textmate.rst
diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst
deleted file mode 100644
index b3d9b6366..000000000
--- a/doc/user_guide/index.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-
-User Guide
-==========
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   installation
-   run
-   output
-   messages/index
-   options
-   ide_integration/ide-integration
-   pre-commit-integration
-   badge
diff --git a/doc/user_guide/badge.rst b/doc/user_guide/installation/badge.rst
index 8463d40b3..8463d40b3 100644
--- a/doc/user_guide/badge.rst
+++ b/doc/user_guide/installation/badge.rst
diff --git a/doc/user_guide/installation/command_line_installation.rst b/doc/user_guide/installation/command_line_installation.rst
new file mode 100644
index 000000000..e881667ae
--- /dev/null
+++ b/doc/user_guide/installation/command_line_installation.rst
@@ -0,0 +1,36 @@
+.. _installation:
+
+Command line installation
+-------------------------
+
+Pylint is installable using a package manager. Your package manager will find a version that
+works with your interpreter. We recommend ``pip``:
+
+.. code-block:: sh
+
+   pip install pylint
+
+Use the newest Python interpreter if you can.
+
+It's possible to analyse code written for older interpreters by using the ``py-version``
+option and setting it to the old interpreter. For example you can check that there are
+no ``f-strings`` in Python 3.5 code using Python 3.8 with an up-to-date pylint even if
+Python 3.5 is past end of life (EOL).
+
+We do not guarantee that ``py-version`` will work for all EOL python interpreters indefinitely,
+(for anything before python 3.5, it probably won't). If a newer version does not work for you,
+the best available pylint might be an old version that works with your old interpreter but
+without the bug fixes and features of later versions.
+
+.. note::
+    You can also use ``conda`` or your system package manager on debian based OS.
+    These package managers lag a little behind as they are maintained by a separate
+    entity on a slower release cycle.
+
+    .. code-block:: sh
+
+       conda install pylint
+
+    .. code-block:: sh
+
+       sudo apt-get install pylint
diff --git a/doc/user_guide/ide_integration/flymake-emacs.rst b/doc/user_guide/installation/ide_integration/flymake-emacs.rst
index 44b9b3262..44b9b3262 100644
--- a/doc/user_guide/ide_integration/flymake-emacs.rst
+++ b/doc/user_guide/installation/ide_integration/flymake-emacs.rst
diff --git a/doc/user_guide/installation.rst b/doc/user_guide/installation/ide_integration/index.rst
index 066cfe822..c1bf5eb4d 100644
--- a/doc/user_guide/installation.rst
+++ b/doc/user_guide/installation/ide_integration/index.rst
@@ -1,47 +1,11 @@
-.. _installation:
-
-Installation
-============
-
-Command line
-------------
-
-Pylint is installable using a package manager. Your package manager will find a version that
-works with your interpreter. We recommend ``pip``:
-
-.. code-block:: sh
-
-   pip install pylint
-
-Use the newest Python interpreter if you can.
-
-It's possible to analyse code written for older interpreters by using the ``py-version``
-option and setting it to the old interpreter. For example you can check that there are
-no ``f-strings`` in Python 3.5 code using Python 3.8 with an up-to-date pylint even if
-Python 3.5 is past end of life (EOL).
-
-We do not guarantee that ``py-version`` will work for all EOL python interpreters indefinitely,
-(for anything before python 3.5, it's probably not). If a newer version does not work for you,
-the best available pylint might be an old version that works with your old interpreter but
-without the bug fixes and feature of later versions.
-
-NB: You can also use ``conda`` or your system package manager on debian based OS.
-These package managers lag a little behind as they are maintained by a separate
-entity on a slower release cycle.
-
-.. code-block:: sh
-
-   conda install pylint
-
-.. code-block:: sh
-
-   sudo apt-get install pylint
-
+.. _ide-integration:
 
-Editor integration
-------------------
+###########################
+ Editor and IDE integration
+###########################
 
-.. _ide-integration:
+Pylint can be integrated in various editors and IDE's.
+Below you can find tutorials for some of the most common ones.
 
 - Eclipse_
 - Emacs_
@@ -77,3 +41,11 @@ Editor integration
 .. _Visual Studio Code: https://code.visualstudio.com/docs/python/linting#_pylint
 .. _Visual Studio Code Pylint Extension: https://marketplace.visualstudio.com/items?itemName=ms-python.pylint
 .. _WingIDE: https://wingware.com/doc/warnings/external-checkers
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   flymake-emacs.rst
+   textmate.rst
diff --git a/doc/user_guide/ide_integration/textmate.rst b/doc/user_guide/installation/ide_integration/textmate.rst
index 3486db340..3486db340 100644
--- a/doc/user_guide/ide_integration/textmate.rst
+++ b/doc/user_guide/installation/ide_integration/textmate.rst
diff --git a/doc/user_guide/installation/index.rst b/doc/user_guide/installation/index.rst
new file mode 100644
index 000000000..7c764fcfc
--- /dev/null
+++ b/doc/user_guide/installation/index.rst
@@ -0,0 +1,18 @@
+Installation
+============
+
+Pylint can be installed:
+
+- As a command line tool
+- Integrated in your editor/ide
+- As a pre-commit hook
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   command_line_installation.rst
+   ide_integration/index
+   pre-commit-integration.rst
+   badge
diff --git a/doc/user_guide/pre-commit-integration.rst b/doc/user_guide/installation/pre-commit-integration.rst
index 62dfbcfd0..62dfbcfd0 100644
--- a/doc/user_guide/pre-commit-integration.rst
+++ b/doc/user_guide/installation/pre-commit-integration.rst
diff --git a/doc/user_guide/options.rst b/doc/user_guide/options.rst
deleted file mode 100644
index 135034df9..000000000
--- a/doc/user_guide/options.rst
+++ /dev/null
@@ -1,9 +0,0 @@
-=============
-Configuration
-=============
-
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   configuration/all-options
diff --git a/doc/user_guide/usage/index.rst b/doc/user_guide/usage/index.rst
new file mode 100644
index 000000000..7adc369c9
--- /dev/null
+++ b/doc/user_guide/usage/index.rst
@@ -0,0 +1,10 @@
+Usage
+=====
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   run
+   output
diff --git a/doc/user_guide/output.rst b/doc/user_guide/usage/output.rst
index 75b92ff80..c98eb8476 100644
--- a/doc/user_guide/output.rst
+++ b/doc/user_guide/usage/output.rst
@@ -23,7 +23,7 @@ a colorized report to stdout at the same time:
 
 
 Custom message formats
-''''''''''''''''''''''''''''
+''''''''''''''''''''''
 
 You can customize the exact way information are displayed using the
 `--msg-template=<format string>` option. The `format string` uses the
diff --git a/doc/user_guide/run.rst b/doc/user_guide/usage/run.rst
index 9a15d04a3..9a15d04a3 100644
--- a/doc/user_guide/run.rst
+++ b/doc/user_guide/usage/run.rst