[refactor] Better link and toc definition for overview of messages

Author: Pierre-Sassoulas

doc/conf.py

@@ -53,6 +53,7 @@
     "user_guide/ide-integration": "installation.html",
     "messages/index": "user_guide/messages/index.html",
     "messages/messages_introduction": "user_guide/messages/index.html",
+    "messages/messages_list": "user_guide/messages/messages_overview.html",
     "user_guide/message-control": "user_guide/messages/message-control.html",
 }
 

doc/exts/pylint_messages.py

@@ -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 an optional checker which requires the ``{message.checker_module_name}``
+  plugin to be loaded. See: :ref:`{message.checker_module_name}`.
 
 """
             )
@@ -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/user_guide/messages/index.rst

@@ -8,21 +8,23 @@ Messages
   :maxdepth: 2
   :hidden:
 
-
-  messages_list.rst
+  messages_overview.rst
   message-control.rst
 
+Messages categories
+===================
+
 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)
+* :ref:`Fatal <fatal-category>` (1)
+* :ref:`Error <error-category>` (2)
+* :ref:`Warning <warning-category>` (4)
+* :ref:`Convention <convention-category>` (8)
+* :ref:`Refactor <refactor-category>` (16)
+* :ref:`Information <information-category>` (NA)
 
-A list of these messages can be found in :ref:`messages-list`
+An overview of these messages can be found in :ref:`messages-overview`
 
 Disabling messages
 ==================