Merge 47a6609 into d11bfec

doc/exts/pylint_extensions.py

@@ -72,7 +72,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_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"):
@@ -150,7 +150,7 @@ def _write_options_page(options: OptionsDataDict, linter: PyLinter) -> None:
     ) as stream:
         stream.write(
             f"""
-{get_rst_title("All pylint options", "=")}
+{get_rst_title("All pylint options", "#")}
 
 {sections_string}
 """

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

@@ -11,7 +11,7 @@
 from typing import TYPE_CHECKING, Any, TextIO
 
 from pylint.constants import MAIN_CHECKER_NAME
-from pylint.utils.utils import get_rst_section, get_rst_title
+from pylint.utils.utils import get_rst_title
 
 if TYPE_CHECKING:
     from pylint.lint.pylinter import PyLinter
@@ -44,26 +44,7 @@ def _get_checkers_infos(linter: PyLinter) -> dict[str, dict[str, Any]]:
 
 def _get_checkers_documentation(linter: PyLinter) -> str:
     """Get documentation for individual checkers."""
-    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"
-    result += get_rst_title("Pylint checkers' options and switches", "-")
+    result = get_rst_title("Pylint checkers' messages and reports", "-")
     result += """\
 
 Pylint checkers can provide three set of features:
@@ -80,7 +61,7 @@ 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=False)
     return result
 
 

tests/lint/unittest_lint.py

@@ -601,12 +601,9 @@ def test_full_documentation(linter: PyLinter) -> None:
     # A few spot checks only
     for re_str in (
         # auto-generated text
-        "^Pylint global options and switches$",
         "Verbatim name of the checker is ``variables``",
         # messages
         "^:undefined-loop-variable \\(W0631\\): *",
-        # options
-        "^:dummy-variables-rgx:",
     ):
         regexp = re.compile(re_str, re.MULTILINE)
         assert re.search(regexp, output)

tests/test_self.py

@@ -1359,7 +1359,7 @@ class TestCallbackOptions:
             (["--list-groups"], "nonascii-checker"),
             (["--list-conf-levels"], "Confidence(name='HIGH', description="),
             (["--list-extensions"], "pylint.extensions.empty_comment"),
-            (["--full-documentation"], "Pylint global options and switches"),
+            (["--full-documentation"], "Basic checker"),
             (["--long-help"], "Environment variables:"),
         ],
     )