[doc] Move all messages documentation to user_guide/messages

Author: Pierre-Sassoulas

.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

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"

doc/conf.py

@@ -51,6 +51,9 @@
     "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.

doc/exts/pylint_messages.py

@@ -23,7 +23,7 @@
 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"

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

doc/messages/index.rst

@@ -9,7 +9,7 @@ User Guide
    installation
    run
    output
-   message-control
+   messages/index
    options
    ide_integration/ide-integration
    pre-commit-integration

doc/messages/messages_introduction.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`

doc/user_guide/index.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.