Work in progress, cross link between checker and option section

Author: Pierre-Sassoulas

doc/exts/pylint_extensions.py

@@ -20,6 +20,10 @@
 from pylint.utils import get_rst_title
 
 
+def _get_checker_extension_rst_anchor(checker: str) -> str:
+    return f".. _{checker.capitalize()}:\n\n"
+
+
 # pylint: disable-next=unused-argument
 def builder_inited(app: Optional[Sphinx]) -> None:
     """Output full documentation in ReST format for all extension modules."""
@@ -60,7 +64,7 @@ def builder_inited(app: Optional[Sphinx]) -> None:
         )
         stream.write("Pylint provides the following optional plugins:\n\n")
         for module in modules:
-            stream.write(f"- :ref:`{module}`\n")
+            stream.write(f"- {_get_module_reference(module)}\n")
         stream.write("\n")
         stream.write(
             "You can activate any or all of these extensions "
@@ -89,6 +93,10 @@ def builder_inited(app: Optional[Sphinx]) -> None:
             )
 
 
+def _get_module_reference(module: str) -> str:
+    return f":ref:`{module}`"
+
+
 def get_plugins_info(linter, doc_files):
     by_checker = {}
     for checker in linter.get_checkers():

doc/exts/pylint_options.py

@@ -63,11 +63,21 @@ def _get_all_options(linter: PyLinter) -> OptionsDataDict:
     return all_options
 
 
+def _get_checker_title(checker: str) -> str:
+    result = _get_checker_configuration_rst_anchor(checker)
+    result += get_rst_title(f"``{checker.capitalize()}`` **Checker**", "-")
+    result += f":ref:`See the description of the checker itself <pylint.extensions.{checker}>`.\n\n"
+    return result
+
+
+def _get_checker_configuration_rst_anchor(checker: str) -> str:
+    return f".. _{checker.capitalize()}_configuration:\n\n"
+
+
 def _create_checker_section(
     checker: str, options: list[OptionsData], linter: PyLinter
 ) -> str:
-    checker_string = get_rst_title(f"``{checker.capitalize()}`` **Checker**", "-")
-
+    checker_string = _get_checker_title(checker)
     toml_doc = tomlkit.document()
     pylint_tool_table = tomlkit.table(is_super_table=True)
     toml_doc.add(tomlkit.key(["tool", "pylint"]), pylint_tool_table)

doc/user_guide/checkers/extensions.rst

@@ -41,6 +41,7 @@ Broad Try Clause checker
 
 This checker is provided by ``pylint.extensions.broad_try_clause``.
 Verbatim name of the checker is ``broad_try_clause``.
+:ref:`See documentation on possible options <broad_try_clause_configuration>`.
 
 Broad Try Clause checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -55,6 +56,7 @@ Code Style checker
 
 This checker is provided by ``pylint.extensions.code_style``.
 Verbatim name of the checker is ``code_style``.
+:ref:`See documentation on possible options <code_style_configuration>`.
 
 Code Style checker Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -84,6 +86,7 @@ Compare-To-Empty-String checker
 
 This checker is provided by ``pylint.extensions.emptystring``.
 Verbatim name of the checker is ``compare-to-empty-string``.
+:ref:`See documentation on possible options <compare-to-empty-string_configuration>`.
 
 Compare-To-Empty-String checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -98,6 +101,7 @@ Compare-To-Zero checker
 
 This checker is provided by ``pylint.extensions.comparetozero``.
 Verbatim name of the checker is ``compare-to-zero``.
+:ref:`See documentation on possible options <compare-to-zero_configuration>`.
 
 Compare-To-Zero checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -112,6 +116,7 @@ Comparison-Placement checker
 
 This checker is provided by ``pylint.extensions.comparison_placement``.
 Verbatim name of the checker is ``comparison-placement``.
+:ref:`See documentation on possible options <comparison-placement_configuration>`.
 
 Comparison-Placement checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -128,6 +133,7 @@ Confusing Elif checker
 
 This checker is provided by ``pylint.extensions.confusing_elif``.
 Verbatim name of the checker is ``confusing_elif``.
+:ref:`See documentation on possible options <confusing_elif_configuration>`.
 
 Confusing Elif checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -145,6 +151,7 @@ Consider-Using-Any-Or-All checker
 
 This checker is provided by ``pylint.extensions.for_any_all``.
 Verbatim name of the checker is ``consider-using-any-or-all``.
+:ref:`See documentation on possible options <consider-using-any-or-all_configuration>`.
 
 Consider-Using-Any-Or-All checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -160,6 +167,7 @@ Consider Ternary Expression checker
 
 This checker is provided by ``pylint.extensions.consider_ternary_expression``.
 Verbatim name of the checker is ``consider_ternary_expression``.
+:ref:`See documentation on possible options <consider_ternary_expression_configuration>`.
 
 Consider Ternary Expression checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -175,6 +183,7 @@ Deprecated Builtins checker
 
 This checker is provided by ``pylint.extensions.bad_builtin``.
 Verbatim name of the checker is ``deprecated_builtins``.
+:ref:`See documentation on possible options <deprecated_builtins_configuration>`.
 
 Deprecated Builtins checker Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -203,6 +212,7 @@ Design checker
 
 This checker is provided by ``pylint.extensions.mccabe``.
 Verbatim name of the checker is ``design``.
+:ref:`See documentation on possible options <design_configuration>`.
 
 Design checker Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -258,6 +268,7 @@ Docstyle checker
 
 This checker is provided by ``pylint.extensions.docstyle``.
 Verbatim name of the checker is ``docstyle``.
+:ref:`See documentation on possible options <docstyle_configuration>`.
 
 Docstyle checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -274,6 +285,7 @@ Else If Used checker
 
 This checker is provided by ``pylint.extensions.check_elif``.
 Verbatim name of the checker is ``else_if_used``.
+:ref:`See documentation on possible options <else_if_used_configuration>`.
 
 Else If Used checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -289,6 +301,7 @@ Eq-Without-Hash checker
 
 This checker is provided by ``pylint.extensions.eq_without_hash``.
 Verbatim name of the checker is ``eq-without-hash``.
+:ref:`See documentation on possible options <eq-without-hash_configuration>`.
 
 Eq-Without-Hash checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -304,6 +317,7 @@ Import-Private-Name checker
 
 This checker is provided by ``pylint.extensions.private_import``.
 Verbatim name of the checker is ``import-private-name``.
+:ref:`See documentation on possible options <import-private-name_configuration>`.
 
 Import-Private-Name checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -320,6 +334,7 @@ Multiple Types checker
 
 This checker is provided by ``pylint.extensions.redefined_variable_type``.
 Verbatim name of the checker is ``multiple_types``.
+:ref:`See documentation on possible options <multiple_types_configuration>`.
 
 Multiple Types checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -334,6 +349,7 @@ No Self Use checker
 
 This checker is provided by ``pylint.extensions.no_self_use``.
 Verbatim name of the checker is ``no_self_use``.
+:ref:`See documentation on possible options <no_self_use_configuration>`.
 
 No Self Use checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -349,6 +365,7 @@ Overlap-Except checker
 
 This checker is provided by ``pylint.extensions.overlapping_exceptions``.
 Verbatim name of the checker is ``overlap-except``.
+:ref:`See documentation on possible options <overlap-except_configuration>`.
 
 Overlap-Except checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -363,6 +380,7 @@ Parameter Documentation checker
 
 This checker is provided by ``pylint.extensions.docparams``.
 Verbatim name of the checker is ``parameter_documentation``.
+:ref:`See documentation on possible options <parameter_documentation_configuration>`.
 
 Parameter Documentation checker Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -563,6 +581,7 @@ Redefined-Loop-Name checker
 
 This checker is provided by ``pylint.extensions.redefined_loop_name``.
 Verbatim name of the checker is ``redefined-loop-name``.
+:ref:`See documentation on possible options <redefined-loop-name_configuration>`.
 
 Redefined-Loop-Name checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -577,6 +596,7 @@ Refactoring checker
 
 This checker is provided by ``pylint.extensions.empty_comment``.
 Verbatim name of the checker is ``refactoring``.
+:ref:`See documentation on possible options <refactoring_configuration>`.
 
 Refactoring checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -591,6 +611,7 @@ Set Membership checker
 
 This checker is provided by ``pylint.extensions.set_membership``.
 Verbatim name of the checker is ``set_membership``.
+:ref:`See documentation on possible options <set_membership_configuration>`.
 
 Set Membership checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -606,6 +627,7 @@ Typing checker
 
 This checker is provided by ``pylint.extensions.typing``.
 Verbatim name of the checker is ``typing``.
+:ref:`See documentation on possible options <typing_configuration>`.
 
 Typing checker Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -639,6 +661,7 @@ While Used checker
 
 This checker is provided by ``pylint.extensions.while_used``.
 Verbatim name of the checker is ``while_used``.
+:ref:`See documentation on possible options <while_used_configuration>`.
 
 While Used checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^