Modify message generation

Author: Pierre-Sassoulas

.readthedocs.yaml

@@ -14,3 +14,7 @@ build:
   os: ubuntu-20.04
   tools:
     python: "3.8"
+
+Type: Page Redirect
+From URL: example.html
+To URL: examples/intro.html

doc/exts/pylint_messages.py

@@ -248,15 +248,11 @@ def _write_messages_list_page(
     with open(messages_file, "w", encoding="utf-8") as stream:
         # Write header of file
         stream.write(
-            f""".. _messages-list:
-
-{get_rst_title("Overview of all Pylint messages", "=")}
+            """.. _messages-list:
 ..
   NOTE This file is auto-generated. Make any changes to the associated
   docs extension in 'pylint_messages.py'.
 
-Pylint can emit the following messages:
-
 """
         )
 
@@ -280,7 +276,7 @@ def _write_messages_list_page(
 
             # Write list per category
             stream.write(
-                f"""{get_rst_title(category.capitalize(), "-")}
+                f"""{get_rst_title(category.capitalize(), "=")}
 All messages in the {category} category:
 
 .. toctree::

doc/user_guide/index.rst

@@ -15,8 +15,6 @@ User Guide
    features
    additional_commands/index.rst
    messages/index.rst
-   messages/message_control.rst
-   messages/messages_list.rst
    output
    options
    c_extensions

doc/user_guide/messages/index.rst

@@ -3,8 +3,7 @@
 Messages
 ========
 
-Pylint can emit various messages. These are categorized according
-to categories corresponding to bit-encoded exit codes:
+Pylint messages are categorized and each category correspond to a bit-encoded exit codes:
 
 * :ref:`Fatal <user_guide/messages/messages_list:Fatal>` (1)
 * :ref:`Error <user_guide/messages/messages_list:Error>` (2)
@@ -13,10 +12,15 @@ to categories corresponding to bit-encoded exit codes:
 * :ref:`Refactor <user_guide/messages/messages_list:Refactor>` (16)
 * :ref:`Information <user_guide/messages/messages_list:Information>` (NA)
 
-A list of these messages can be found in :ref:`messages-list`
-
-``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
+Each message can be enabled / disabled from the command line or from the configuration
 file, as well as from the code itself.
 
 For more detail see :ref:`message_control`
+
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   message_control
+   messages_list

doc/user_guide/messages/message_control.rst

@@ -1,7 +1,7 @@
 .. _message_control:
 
 Messages control
-================
+----------------
 
 In order to control messages, ``pylint`` accepts the following values:
 
@@ -25,7 +25,7 @@ In order to control messages, ``pylint`` accepts the following values:
 
 
 Module disable
---------------
+^^^^^^^^^^^^^^
 
 Add ``#pylint: skip-file`` at the beginning of the module.
 
@@ -41,7 +41,7 @@ top of the file: ::
 
 
 Inline disable
---------------
+^^^^^^^^^^^^^^
 
 For just a single line, add ``#pylint: disable=some-message,another-one`` at the end of
 the desired line of code. Since Pylint 2.10 you can also use ``#pylint: disable-next=...``
@@ -50,7 +50,7 @@ list of messages you want to disable.
 
 
 Block disables
---------------
+^^^^^^^^^^^^^^
 
 For larger amounts of code, you can add ``#pylint: disable=...`` at the block level
 to disable messages for the entire block. It's possible to re-enable a message for the
@@ -225,7 +225,7 @@ Here's an example with all these rules in a single place:
 
 
 Detecting useless disables
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 As pylint gets better and false positives are removed,
 disables that became useless can accumulate and clutter the code.

doc/user_guide/messages/messages_list.rst

@@ -1,16 +1,10 @@
 .. _messages-list:
-
-Overview of all Pylint messages
-===============================
-
 ..
   NOTE This file is auto-generated. Make any changes to the associated
   docs extension in 'pylint_messages.py'.
 
-Pylint can emit the following messages:
-
 Fatal
------
+=====
 
 All messages in the fatal category:
 
@@ -34,7 +28,7 @@ All renamed messages in the fatal category:
 
 
 Error
------
+=====
 
 All messages in the error category:
 
@@ -178,7 +172,7 @@ All renamed messages in the error category:
 
 
 Warning
--------
+=======
 
 All messages in the warning category:
 
@@ -345,7 +339,7 @@ All renamed messages in the warning category:
 
 
 Convention
-----------
+==========
 
 All messages in the convention category:
 
@@ -423,7 +417,7 @@ All renamed messages in the convention category:
 
 
 Refactor
---------
+========
 
 All messages in the refactor category:
 
@@ -512,7 +506,7 @@ All renamed messages in the refactor category:
 
 
 Information
------------
+===========
 
 All messages in the information category: