[doc] Move all messages documentation to user_guide/messages

11 files changed, 51 insertions, 37 deletions

diff --git a/.gitignore b/.gitignore
index b4fa458be..ea96bb688 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,7 +9,14 @@
 /pylint.egg-info/
 .tox
 *.sw[a-z]
-doc/messages/
+# Can't use | operator in .gitignore, see
+# https://unix.stackexchange.com/a/31806/189111
+doc/user_guide/messages/convention/
+doc/user_guide/messages/error/
+doc/user_guide/messages/fatal/
+doc/user_guide/messages/information/
+doc/user_guide/messages/refactor/
+doc/user_guide/messages/warning/
 doc/technical_reference/extensions.rst
 doc/technical_reference/features.rst
 doc/user_guide/configuration/all-options.rst
diff --git a/doc/Makefile b/doc/Makefile
index 73ab49ae5..ee03e051e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -36,8 +36,9 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 
 clean:
-	-rm -rf $(BUILDDIR)/* messages/convention messages/error messages/fatal messages/information \
-	  messages/refactor messages/warning technical_reference/extensions.rst technical_reference/features.rst
+	-rm -rf $(BUILDDIR)/* user_guide/messages/convention user_guide/messages/error \
+	  user_guide/messages/fatal user_guide/messages/information user_guide/messages/refactor \
+	  user_guide/messages/warning technical_reference/extensions.rst technical_reference/features.rst
 
 install-dependencies:
 	@echo "Install dependencies"
diff --git a/doc/conf.py b/doc/conf.py
index 63bb99976..5134ffe67 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -51,6 +51,9 @@ redirects: dict[str, str] = {
     "intro": "index.html",
     "support": "contact.html",
     "user_guide/ide-integration": "installation.html",
+    "messages/index": "user_guide/messages/index.html",
+    "messages/messages_introduction": "user_guide/messages/index.html",
+    "user_guide/message-control": "user_guide/messages/message-control.html",
 }
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py
index 4388985d9..7b09f0ff6 100644
--- a/doc/exts/pylint_messages.py
+++ b/doc/exts/pylint_messages.py
@@ -23,7 +23,7 @@ from pylint.utils import get_rst_title
 PYLINT_BASE_PATH = Path(__file__).resolve().parent.parent.parent
 """Base path to the project folder."""
 
-PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages"
+PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc/user_guide/messages"
 """Path to the messages documentation folder."""
 
 PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages"
diff --git a/doc/index.rst b/doc/index.rst
index 0a77c7463..df9a4c133 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -44,7 +44,6 @@ re-evaluate and re-enable messages as your priorities evolve.
    tutorial
    user_guide/index.rst
    how_tos/index.rst
-   messages/index.rst
    technical_reference/index.rst
    development_guide/index.rst
    additional_commands/index.rst
diff --git a/doc/messages/index.rst b/doc/messages/index.rst
deleted file mode 100644
index aceca53f6..000000000
--- a/doc/messages/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _messages:
-
-Messages
-===================
-
-.. toctree::
-  :maxdepth: 1
-  :titlesonly:
-
-  messages_introduction
-  messages_list
diff --git a/doc/messages/messages_introduction.rst b/doc/messages/messages_introduction.rst
deleted file mode 100644
index e351d1b9b..000000000
--- a/doc/messages/messages_introduction.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-.. _messages-introduction:
-
-Message categories
-=====================
-
-Pylint can emit various messages. These are categorized according to categories::
-
-    Convention
-    Error
-    Fatal
-    Information
-    Refactor
-    Warning
-
-A list of these messages can be found here: :ref:`messages-list`
diff --git a/doc/user_guide/index.rst b/doc/user_guide/index.rst
index 84947b530..739a22fa5 100644
--- a/doc/user_guide/index.rst
+++ b/doc/user_guide/index.rst
@@ -9,7 +9,7 @@ User Guide
    installation
    run
    output
-   message-control
+   messages/index
    options
    ide_integration/ide-integration
    pre-commit-integration
diff --git a/doc/user_guide/messages/index.rst b/doc/user_guide/messages/index.rst
new file mode 100644
index 000000000..f21efb539
--- /dev/null
+++ b/doc/user_guide/messages/index.rst
@@ -0,0 +1,34 @@
+.. _messages:
+
+########
+Messages
+########
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+
+  messages_list.rst
+  message-control.rst
+
+Pylint can emit various messages. These are categorized according
+to categories corresponding to bit-encoded exit codes:
+
+* :ref:`Fatal` (1)
+* :ref:`Error` (2)
+* :ref:`Warning` (4)
+* :ref:`Convention` (8)
+* :ref:`Refactor` (16)
+* :ref:`Information` (NA)
+
+A list of these messages can be found in :ref:`messages-list`
+
+Disabling messages
+==================
+
+``pylint`` has an advanced message control for its checks, offering the ability
+to enable / disable a message either from the command line or from the configuration
+file, as well as from the code itself.
+
+For more detail see :ref:`message-control`
diff --git a/doc/user_guide/message-control.rst b/doc/user_guide/messages/message-control.rst
index 0f735e533..4ac6cec4b 100644
--- a/doc/user_guide/message-control.rst
+++ b/doc/user_guide/messages/message-control.rst
@@ -3,11 +3,7 @@
 Messages control
 ================
 
-``pylint`` has an advanced message control for its checks, offering the ability
-to enable / disable a message either from the command line or from the configuration
-file, as well as from the code itself.
-
-For all of these controls, ``pylint`` accepts the following values:
+In order to control messages, ``pylint`` accepts the following values:
 
 * a symbolic message: ``no-member``, ``undefined-variable`` etc.
 
diff --git a/doc/messages/messages_list.rst b/doc/user_guide/messages/messages_list.rst
index c7674dcb7..c7674dcb7 100644
--- a/doc/messages/messages_list.rst
+++ b/doc/user_guide/messages/messages_list.rst