[doc] Add generated disclaimer in result of generated documentation

Author: Pierre-Sassoulas

doc/exts/pylint_extensions.py

@@ -51,6 +51,13 @@ def builder_inited(app: Optional[Sphinx]) -> None:
     )
     with open(extensions_doc, "w", encoding="utf-8") as stream:
         stream.write(get_rst_title("Optional checkers", "="))
+        stream.write(
+            """
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_extensions.py'.
+
+"""
+        )
         stream.write("Pylint provides the following optional plugins:\n\n")
         for module in modules:
             stream.write(f"- :ref:`{module}`\n")

doc/exts/pylint_features.py

@@ -15,7 +15,7 @@
 from sphinx.application import Sphinx
 
 from pylint.lint import PyLinter
-from pylint.utils import print_full_documentation
+from pylint.utils import get_rst_title, print_full_documentation
 
 
 # pylint: disable-next=unused-argument
@@ -28,9 +28,14 @@ def builder_inited(app: Optional[Sphinx]) -> None:
     linter.load_default_plugins()
     features = os.path.join(base_path, "doc", "user_guide", "checkers", "features.rst")
     with open(features, "w", encoding="utf-8") as stream:
-        stream.write("Pylint features\n")
-        stream.write("===============\n\n")
-        stream.write(".. generated by pylint --full-documentation\n\n")
+        stream.write(get_rst_title("Pylint features", "="))
+        stream.write(
+            """
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_features.py'.
+
+"""
+        )
         print_full_documentation(linter, stream)
 
 

doc/exts/pylint_messages.py

@@ -254,9 +254,9 @@ def _write_messages_list_page(
 
 {"#" * len(title)}
 {get_rst_title(title, "#")}
-..
-  NOTE This file is auto-generated. Make any changes to the associated
-  docs extension in 'doc/exts/pylint_messages.py'.
+
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_messages.py'.
 
 Pylint can emit the following messages:
 

doc/exts/pylint_options.py

@@ -67,7 +67,6 @@ def _create_checker_section(
     checker: str, options: list[OptionsData], linter: PyLinter
 ) -> str:
     checker_string = get_rst_title(f"``{checker.capitalize()}`` Checker", "^")
-
     toml_doc = tomlkit.document()
     pylint_tool_table = tomlkit.table(is_super_table=True)
     toml_doc.add(tomlkit.key(["tool", "pylint"]), pylint_tool_table)
@@ -133,7 +132,11 @@ def _create_checker_section(
 
 def _write_options_page(options: OptionsDataDict, linter: PyLinter) -> None:
     """Create or overwrite the options page."""
-    sections: list[str] = [get_rst_title("Standard Checkers:", "^")]
+    sections: list[str] = [
+        ".. This file is auto-generated. Make any changes to the associated\n"
+        ".. docs extension in 'doc/exts/pylint_options.py'.",
+        get_rst_title("Standard Checkers:", "^"),
+    ]
     found_extensions = False
 
     for checker, checker_options in options.items():

doc/user_guide/checkers/extensions.rst

@@ -1,5 +1,9 @@
 Optional checkers
 =================
+
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_extensions.py'.
+
 Pylint provides the following optional plugins:
 
 - :ref:`pylint.extensions.bad_builtin`

doc/user_guide/checkers/features.rst

@@ -1,7 +1,8 @@
 Pylint features
 ===============
 
-.. generated by pylint --full-documentation
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_features.py'.
 
 Pylint global options and switches
 ----------------------------------

doc/user_guide/configuration/all-options.rst

@@ -1,5 +1,8 @@
 
 
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_options.py'.
+
 Standard Checkers:
 ^^^^^^^^^^^^^^^^^^
 

doc/user_guide/messages/messages_overview.rst

@@ -5,9 +5,9 @@
 Messages overview
 #################
 
-..
-  NOTE This file is auto-generated. Make any changes to the associated
-  docs extension in 'doc/exts/pylint_messages.py'.
+
+.. This file is auto-generated. Make any changes to the associated
+.. docs extension in 'doc/exts/pylint_messages.py'.
 
 Pylint can emit the following messages: