Remove redundant options documentation and improve formatting

Author: DanielNoord

doc/exts/pylint_extensions.py

@@ -70,7 +70,10 @@ def builder_inited(app: Optional[Sphinx]) -> None:
         for checker, information in sorted(by_checker.items()):
             checker = information["checker"]
             del information["checker"]
-            print(checker.get_full_documentation(**information)[:-1], file=stream)
+            print(
+                checker.get_full_documentation(**information, show_options=False)[:-1],
+                file=stream,
+            )
 
 
 def get_plugins_info(linter, doc_files):

doc/exts/pylint_features.py

@@ -31,7 +31,7 @@ def builder_inited(app: Optional[Sphinx]) -> None:
         stream.write("Pylint features\n")
         stream.write("===============\n\n")
         stream.write(".. generated by pylint --full-documentation\n\n")
-        print_full_documentation(linter, stream)
+        print_full_documentation(linter, stream, False)
 
 
 def setup(app):

doc/exts/pylint_options.py

@@ -66,7 +66,7 @@ def _get_all_options(linter: PyLinter) -> OptionsDataDict:
 def _create_checker_section(
     checker: str, options: list[OptionsData], linter: PyLinter
 ) -> str:
-    checker_string = get_rst_title(f"``{checker.capitalize()}`` Checker", "^")
+    checker_string = get_rst_title(f"``{checker.capitalize()}`` **Checker**", "-")
 
     toml_doc = tomlkit.document()
     pylint_tool_table = tomlkit.table(is_super_table=True)
@@ -76,11 +76,11 @@ def _create_checker_section(
 
     for option in sorted(options, key=lambda x: x.name):
         checker_string += get_rst_title(f"--{option.name}", '"')
-        checker_string += f"\nDescription:\n  *{option.optdict.get('help')}*\n\n"
+        checker_string += f"*{option.optdict.get('help')}*\n\n"
         if option.optdict.get("default") == "":
-            checker_string += 'Default:\n  ``""``\n\n\n'
+            checker_string += '**Default:** ``""``\n\n\n'
         else:
-            checker_string += f"Default:\n  ``{option.optdict.get('default')}``\n\n\n"
+            checker_string += f"**Default:**  ``{option.optdict.get('default')}``\n\n\n"
 
         # Start adding the option to the toml example
         if option.optdict.get("hide_from_config_file"):

pylint/checkers/base_checker.py

@@ -109,6 +109,7 @@ def get_full_documentation(
         reports: tuple[tuple[str, str, ReportsCallable], ...],
         doc: str | None = None,
         module: str | None = None,
+        show_options: bool = True,
     ) -> str:
         result = ""
         checker_title = f"{self.name.replace('_', ' ').title()} checker"
@@ -125,7 +126,7 @@ def get_full_documentation(
             result += f"{cleandoc(doc)}\n\n"
         # options might be an empty generator and not be False when cast to boolean
         options_list = list(options)
-        if options_list:
+        if options_list and show_options:
             result += get_rst_title(f"{checker_title} Options", "^")
             result += f"{get_rst_section(None, options_list)}\n"
         if msgs:

pylint/utils/docs.py

@@ -42,27 +42,29 @@ def _get_checkers_infos(linter: PyLinter) -> dict[str, dict[str, Any]]:
     return by_checker
 
 
-def _get_checkers_documentation(linter: PyLinter) -> str:
+def _get_checkers_documentation(linter: PyLinter, show_options: bool = True) -> str:
     """Get documentation for individual checkers."""
-    result = get_rst_title("Pylint global options and switches", "-")
-    result += """
+    result = ""
+    if show_options:
+        result += get_rst_title("Pylint global options and switches", "-")
+        result += """
 Pylint provides global options and switches.
 
 """
-    for checker in linter.get_checkers():
-        name = checker.name
-        if name == MAIN_CHECKER_NAME:
-            if checker.options:
-                with warnings.catch_warnings():
-                    warnings.filterwarnings("ignore", category=DeprecationWarning)
-                    for section, options in checker.options_by_section():
-                        if section is None:
-                            title = "General options"
-                        else:
-                            title = f"{section.capitalize()} options"
-                        result += get_rst_title(title, "~")
-                        assert isinstance(options, list)
-                        result += f"{get_rst_section(None, options)}\n"
+        for checker in linter.get_checkers():
+            name = checker.name
+            if name == MAIN_CHECKER_NAME:
+                if checker.options:
+                    with warnings.catch_warnings():
+                        warnings.filterwarnings("ignore", category=DeprecationWarning)
+                        for section, options in checker.options_by_section():
+                            if section is None:
+                                title = "General options"
+                            else:
+                                title = f"{section.capitalize()} options"
+                            result += get_rst_title(title, "~")
+                            assert isinstance(options, list)
+                            result += f"{get_rst_section(None, options)}\n"
     result += get_rst_title("Pylint checkers' options and switches", "-")
     result += """\
 
@@ -80,10 +82,16 @@ def _get_checkers_documentation(linter: PyLinter) -> str:
         information = by_checker[checker_name]
         checker = information["checker"]
         del information["checker"]
-        result += checker.get_full_documentation(**information)
+        result += checker.get_full_documentation(
+            **information, show_options=show_options
+        )
     return result
 
 
-def print_full_documentation(linter: PyLinter, stream: TextIO = sys.stdout) -> None:
+def print_full_documentation(
+    linter: PyLinter, stream: TextIO = sys.stdout, show_options: bool = True
+) -> None:
     """Output a full documentation in ReST format."""
-    print(_get_checkers_documentation(linter)[:-1], file=stream)
+    print(
+        _get_checkers_documentation(linter, show_options=show_options)[:-1], file=stream
+    )