Move the messages documentation to the user guide

.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

@@ -45,13 +45,30 @@
     "sphinx_reredirects",
 ]
 
+
+# Single file redirects are handled in this file and can be done by a pylint
+# contributor if no englobing full directory redirect is applied first. See:
 # https://documatt.gitlab.io/sphinx-reredirects/usage.html
+# Directory redirects are handled in ReadTheDoc admin interface and can only be done
+# by pylint maintainers at the following URL:
+# https://readthedocs.org/dashboard/pylint/redirects/
+DIRECTORY_REDIRECT = [
+    # This list has no effect it must be manually updated from the Read the doc conf
+    "messages/",
+]
 redirects: dict[str, str] = {
     # "<source>": "<target>"
     "intro": "index.html",
     "support": "contact.html",
     "user_guide/ide-integration": "installation.html",
+    "user_guide/message-control": "user_guide/messages/message_control.html",
 }
+for m in redirects:
+    for r in DIRECTORY_REDIRECT:
+        assert not m.startswith(r), (
+            f"Redirection will silentely fail: '{m}' start with '{r}' and "
+            "the whole directory is redirected by ReadtheDoc conf already."
+        )
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

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"
@@ -230,7 +230,8 @@ def _write_single_message_page(category_dir: Path, message: MessageData) -> None
             stream.write(
                 f"""
 .. note::
-  This message is emitted by an optional checker which requires the ``{message.checker_module_name}`` plugin to be loaded. See: :ref:`{message.checker_module_name}`.
+  This message is emitted by the optional :ref:`'{message.checker}'<{message.checker_module_name}>` checker which requires the ``{message.checker_module_name}``
+  plugin to be loaded.
 
 """
             )
@@ -244,22 +245,24 @@ def _write_messages_list_page(
     messages_dict: MessagesDict, old_messages_dict: OldMessagesDict
 ) -> None:
     """Create or overwrite the page with the list of all messages."""
-    messages_file = os.path.join(PYLINT_MESSAGES_PATH, "messages_list.rst")
+    messages_file = os.path.join(PYLINT_MESSAGES_PATH, "messages_overview.rst")
     with open(messages_file, "w", encoding="utf-8") as stream:
         # Write header of file
+        title = "Messages overview"
         stream.write(
-            f""".. _messages-list:
+            f"""
+.. _messages-overview:
 
-{get_rst_title("Overview of all Pylint messages", "=")}
+{"#" * len(title)}
+{get_rst_title(title, "#")}
 ..
   NOTE This file is auto-generated. Make any changes to the associated
-  docs extension in 'pylint_messages.py'.
+  docs extension in 'doc/exts/pylint_messages.py'.
 
 Pylint can emit the following messages:
 
 """
         )
-
         # Iterate over tuple to keep same order
         for category in (
             "fatal",
@@ -272,15 +275,19 @@ def _write_messages_list_page(
             messages = sorted(messages_dict[category], key=lambda item: item.name)
             old_messages = sorted(old_messages_dict[category], key=lambda item: item[0])
             messages_string = "".join(
-                f"   {category}/{message.name}.rst\n" for message in messages
+                f"   {category}/{message.name}\n" for message in messages
             )
             old_messages_string = "".join(
-                f"   {category}/{old_message[0]}.rst\n" for old_message in old_messages
+                f"   {category}/{old_message[0]}\n" for old_message in old_messages
             )
 
-            # Write list per category
+            # Write list per category. We need the '-category' suffix in the reference
+            # because 'fatal' is also a message's symbol
             stream.write(
-                f"""{get_rst_title(category.capitalize(), "-")}
+                f"""
+.. _{category.lower()}-category:
+
+{get_rst_title(category.capitalize(), "*")}
 All messages in the {category} category:
 
 .. toctree::
@@ -294,9 +301,7 @@ def _write_messages_list_page(
    :maxdepth: 1
    :titlesonly:
 
-{old_messages_string}
-
-"""
+{old_messages_string}"""
             )
 
 

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