Remove redundant options documentation and improve formatting (#6665)

Co-authored-by: Pierre Sassoulas <[email protected]>

Author: DanielNoord

doc/exts/pylint_extensions.py

@@ -83,7 +83,10 @@ def builder_inited(app: Optional[Sphinx]) -> None:
             if i == max_len - 1:
                 # Remove the \n\n at the end of the file
                 j = -3
-            print(checker.get_full_documentation(**information)[:j], file=stream)
+            print(
+                checker.get_full_documentation(**information, show_options=False)[:j],
+                file=stream,
+            )
 
 
 def get_plugins_info(linter, doc_files):

doc/exts/pylint_features.py

@@ -36,7 +36,7 @@ def builder_inited(app: Optional[Sphinx]) -> None:
 
 """
         )
-        print_full_documentation(linter, stream)
+        print_full_documentation(linter, stream, False)
 
 
 def setup(app):

doc/exts/pylint_options.py

@@ -66,7 +66,9 @@ 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 = f".. _{checker}-options:\n\n"
+    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)
@@ -75,11 +77,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"):
@@ -138,13 +140,13 @@ def _write_options_page(options: OptionsDataDict, linter: PyLinter) -> None:
         ".. This file is auto-generated. Make any changes to the associated\n"
         ".. docs extension in 'doc/exts/pylint_options.py'.\n\n"
         ".. _all-options:",
-        get_rst_title("Standard Checkers:", "^"),
+        get_rst_title("Standard Checkers", "^"),
     ]
     found_extensions = False
 
     for checker, checker_options in options.items():
         if not found_extensions and checker_options[0].extension:
-            sections.append(get_rst_title("Extensions:", "^"))
+            sections.append(get_rst_title("Extensions", "^"))
             found_extensions = True
         sections.append(_create_checker_section(checker, checker_options, linter))
 

doc/user_guide/checkers/extensions.rst

@@ -42,12 +42,7 @@ Broad Try Clause checker
 This checker is provided by ``pylint.extensions.broad_try_clause``.
 Verbatim name of the checker is ``broad_try_clause``.
 
-Broad Try Clause checker Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:max-try-statements:
-  Maximum number of statements allowed in a try clause
-
-  Default: ``1``
+See also :ref:`broad_try_clause checker's options' documentation <broad_try_clause-options>`
 
 Broad Try Clause checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -69,12 +64,7 @@ Checkers that can improve code consistency.
 As such they don't necessarily provide a performance benefit and
 are often times opinionated.
 
-Code Style checker Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-:max-line-length-suggestions:
-  Max line length for which to sill emit suggestions. Used to prevent optional
-  suggestions which would get split by a code formatter (e.g., black). Will
-  default to the setting for ``max-line-length``.
+See also :ref:`code_style checker's options' documentation <code_style-options>`
 
 Code Style checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -202,12 +192,7 @@ you can use the ``bad-functions`` option::
     $ pylint a.py --load-plugins=pylint.extensions.bad_builtin --bad-functions=apply,reduce
     ...
 
-Deprecated Builtins checker Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:bad-functions:
-  List of builtins function names that should not be used, separated by a comma
-
-  Default: ``map,filter``
+See also :ref:`deprecated_builtins checker's options' documentation <deprecated_builtins-options>`
 
 Deprecated Builtins checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -265,12 +250,7 @@ higher than a preestablished value, which can be controlled through the
     $ pylint a.py --load-plugins=pylint.extensions.mccabe --max-complexity=50
     $
 
-Design checker Options
-^^^^^^^^^^^^^^^^^^^^^^
-:max-complexity:
-  McCabe complexity cyclomatic threshold
-
-  Default: ``10``
+See also :ref:`design checker's options' documentation <design-options>`
 
 Design checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -550,33 +530,7 @@ docstring defining the interface, e.g. a superclass method, after "see"::
 Naming inconsistencies in existing parameter and their type documentations are
 still detected.
 
-Parameter Documentation checker Options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:accept-no-param-doc:
-  Whether to accept totally missing parameter documentation in the docstring of
-  a function that has parameters.
-
-  Default: ``yes``
-:accept-no-raise-doc:
-  Whether to accept totally missing raises documentation in the docstring of a
-  function that raises an exception.
-
-  Default: ``yes``
-:accept-no-return-doc:
-  Whether to accept totally missing return documentation in the docstring of a
-  function that returns a statement.
-
-  Default: ``yes``
-:accept-no-yields-doc:
-  Whether to accept totally missing yields documentation in the docstring of a
-  generator.
-
-  Default: ``yes``
-:default-docstring-type:
-  If the docstring type cannot be guessed the specified docstring type will be
-  used.
-
-  Default: ``default``
+See also :ref:`parameter_documentation checker's options' documentation <parameter_documentation-options>`
 
 Parameter Documentation checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -667,17 +621,7 @@ Typing checker Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Find issue specifically related to type annotations.
 
-Typing checker Options
-^^^^^^^^^^^^^^^^^^^^^^
-:runtime-typing:
-  Set to ``no`` if the app / library does **NOT** need to support runtime
-  introspection of type annotations. If you use type annotations
-  **exclusively** for type checking of an application, you're probably fine.
-  For libraries, evaluate if some users what to access the type hints at
-  runtime first, e.g., through ``typing.get_type_hints``. Applies to Python
-  versions 3.7 - 3.9
-
-  Default: ``yes``
+See also :ref:`typing checker's options' documentation <typing-options>`
 
 Typing checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^