Set up system of code examples and details for message documentation (#5934)

Author: DanielNoord

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
     rev: v1.4
     hooks:
       - id: autoflake
-        exclude: &fixtures tests/functional/|tests/input|tests/regrtest_data/|tests/data/
+        exclude: &fixtures tests/functional/|tests/input|tests/regrtest_data/|tests/data/|doc/data/messages
         args:
           - --in-place
           - --remove-all-unused-imports

doc/conf.py

@@ -73,7 +73,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "data/**"]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 # default_role = None

doc/data/messages/e/empty-docstring/bad.py

@@ -0,0 +1,2 @@
+def foo():
+    pass  # [emtpy-docstring]

doc/data/messages/e/empty-docstring/good.py

@@ -0,0 +1,2 @@
+def foo():
+    """A dummy description."""

doc/data/messages/y/yield-inside-async-function/bad.py

@@ -0,0 +1,2 @@
+async def foo():
+    yield from [1, 2, 3]  # [yield-inside-async-function]

doc/data/messages/y/yield-inside-async-function/details.rst

@@ -0,0 +1 @@
+The message can't be emitted when using Python < 3.5.

doc/data/messages/y/yield-inside-async-function/good.py

@@ -0,0 +1,7 @@
+async def foo():
+    def _inner_foo():
+        yield from [1, 2, 3]
+
+
+async def foo():
+    yield 42

doc/data/messages/y/yield-inside-async-function/related.rst

@@ -0,0 +1 @@
+- `PEP 525 <https://peps.python.org/pep-0525/>`_

doc/exts/pylint_messages.py

@@ -23,6 +23,8 @@
 PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages"
 """Path to the messages documentation folder."""
 
+PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages"
+"""Path to the folder with data for the messages documentation."""
 
 MSG_TYPES_DOC = {k: v if v != "info" else "information" for k, v in MSG_TYPES.items()}
 
@@ -32,6 +34,10 @@ class MessageData(NamedTuple):
     id: str
     name: str
     definition: MessageDefinition
+    good_code: str
+    bad_code: str
+    details: str
+    related_links: str
 
 
 MessagesDict = Dict[str, List[MessageData]]
@@ -47,6 +53,54 @@ def _register_all_checkers_and_extensions(linter: PyLinter) -> None:
     initialize_extensions(linter)
 
 
+def _get_message_data(data_path: Path) -> Tuple[str, str, str, str]:
+    """Get the message data from the specified path."""
+    good_code, bad_code, details, related = "", "", "", ""
+
+    if not data_path.exists():
+        return good_code, bad_code, details, related
+
+    if (data_path / "good.py").exists():
+        with open(data_path / "good.py", encoding="utf-8") as file:
+            file_content = file.readlines()
+            indented_file_content = "".join("  " + i for i in file_content)
+            good_code = f"""
+**Correct code:**
+
+.. code-block:: python
+
+{indented_file_content}"""
+
+    if (data_path / "bad.py").exists():
+        with open(data_path / "bad.py", encoding="utf-8") as file:
+            file_content = file.readlines()
+            indented_file_content = "".join("  " + i for i in file_content)
+            bad_code = f"""
+**Problematic code:**
+
+.. code-block:: python
+
+{indented_file_content}"""
+
+    if (data_path / "details.rst").exists():
+        with open(data_path / "details.rst", encoding="utf-8") as file:
+            file_content_string = file.read()
+            details = f"""
+**Additional details:**
+
+{file_content_string}"""
+
+    if (data_path / "related.rst").exists():
+        with open(data_path / "related.rst", encoding="utf-8") as file:
+            file_content_string = file.read()
+            related = f"""
+**Related links:**
+
+{file_content_string}"""
+
+    return good_code, bad_code, details, related
+
+
 def _get_all_messages(
     linter: PyLinter,
 ) -> Tuple[MessagesDict, OldMessagesDict]:
@@ -72,8 +126,20 @@ def _get_all_messages(
         "information": defaultdict(list),
     }
     for message in linter.msgs_store.messages:
+        message_data_path = (
+            PYLINT_MESSAGES_DATA_PATH / message.symbol[0] / message.symbol
+        )
+        good_code, bad_code, details, related = _get_message_data(message_data_path)
+
         message_data = MessageData(
-            message.checker_name, message.msgid, message.symbol, message
+            message.checker_name,
+            message.msgid,
+            message.symbol,
+            message,
+            good_code,
+            bad_code,
+            details,
+            related,
         )
         messages_dict[MSG_TYPES_DOC[message.msgid[0]]].append(message_data)
 
@@ -108,6 +174,11 @@ def _write_message_page(messages_dict: MessagesDict) -> None:
 
 *{message.definition.description}*
 
+{message.good_code}
+{message.bad_code}
+{message.details}
+{message.related_links}
+
 Created by ``{message.checker}`` checker
 """
                 )