[script] Add :ref: automatically in the documentation

.pre-commit-config.yaml

@@ -122,6 +122,17 @@ repos:
         types: [text]
         files: ^(doc/whatsnew/fragments)
         exclude: doc/whatsnew/fragments/_.*.rst
+      - id: check-message-references
+        name: Check pylint message references
+        entry: python script/check_message_references.py
+        language: system
+        args: ["--fix"]
+        types_or: [python, rst, markdown, text]
+        files: ^doc/(whatsnew|data/messages)/.*\.rst$
+        exclude:
+          \.( doc/development_guide/api/pylint.rst|
+          doc/development_guide/how_tos/custom_checkers.rst| )$
+        pass_filenames: true
   - repo: https://github.com/rstcheck/rstcheck
     rev: "v6.2.5"
     hooks:

doc/data/messages/u/useless-parent-delegation/related.rst

@@ -1 +1 @@
-- `Stackoverflow explanation for 'useless-super-delegation' <https://stackoverflow.com/a/51030674/2519059>`_
+- `Stackoverflow explanation for ':ref:`useless-super-delegation`' <https://stackoverflow.com/a/51030674/2519059>`_

doc/user_guide/checkers/features.rst

@@ -689,11 +689,11 @@ Match Statements checker Messages
 :invalid-match-args-definition (E1902): *`__match_args__` must be a tuple of strings.*
   Emitted if `__match_args__` isn't a tuple of strings required for match.
 :too-many-positional-sub-patterns (E1903): *%s expects %d positional sub-patterns (given %d)*
-  Emitted when the number of allowed positional sub-patterns exceeds the
-  number of allowed sub-patterns specified in `__match_args__`.
+  Emitted when the number of allowed positional sub-patterns exceeds the number
+  of allowed sub-patterns specified in `__match_args__`.
 :multiple-class-sub-patterns (E1904): *Multiple sub-patterns for attribute %s*
-  Emitted when there is more than one sub-pattern for a specific attribute in
-  a class pattern.
+  Emitted when there is more than one sub-pattern for a specific attribute in a
+  class pattern.
 
 
 Method Args checker

doc/whatsnew/0/0.x.rst

@@ -29,7 +29,7 @@ Release date: 2013-04-25
 * Simplify checks for dangerous default values by unifying tests for all
   different mutable compound literals.
 
-* Improve the description for E1124[redundant-keyword-arg]
+* Improve the description for E1124[:ref:`redundant-keyword-arg`]
 
 
 What's New in Pylint 0.27.0?

doc/whatsnew/1/1.0.rst

@@ -19,7 +19,7 @@ Release date: 2013-08-06
 * Do not double-check parameter names with the regex for parameters and
   inline variables.
 
-* Added a new warning missing-final-newline (C0304) for files missing
+* Added a new warning :ref:`missing-final-newline` (C0304) for files missing
   the final newline.
 
 * Methods that are decorated as properties are now treated as attributes
@@ -34,13 +34,13 @@ Release date: 2013-08-06
   pylint can detect that value on the right-hand side is a class
   (like collections.namedtuple()).
 
-* Simplified invalid-name message
+* Simplified :ref:`invalid-name` message
 
 * Added a new warning invalid-encoded-data (W0512) for files that
   contain data that cannot be decoded with the specified or
   default encoding.
 
-* New warning bad-open-mode (W1501) for calls to open (or file) that
+* New warning :ref:`bad-open-mode` (W1501) for calls to open (or file) that
   specify invalid open modes (Original implementation by Sasha Issayev).
 
 * New warning old-style-class (C1001) for classes that do not have any
@@ -49,18 +49,18 @@ Release date: 2013-08-06
 * Add new name type 'class_attribute' for attributes defined
   in class scope. By default, allow both const and variable names.
 
-* New warning trailing-whitespace (C0303) that warns about
+* New warning :ref:`trailing-whitespace` (C0303) that warns about
   trailing whitespace.
 
 * Added a new warning unpacking-in-except (W0712) about unpacking
   exceptions in handlers, which is unsupported in Python 3.
 
-* Add a configuration option for missing-docstring to
+* Add a configuration option for :ref:`missing-docstring` to
   optionally exempt short functions/methods/classes from
   the check.
 
-* Add the type of the offending node to missing-docstring
-  and empty-docstring.
+* Add the type of the offending node to :ref:`missing-docstring`
+  and :ref:`empty-docstring`.
 
 * New utility classes for per-checker unittests in testutils.py
 
@@ -70,7 +70,7 @@ Release date: 2013-08-06
 * Do not treat all variables starting with _ as dummy variables,
   only _ itself.
 
-* Make the line-too-long warning configurable by adding a regex for lines
+* Make the :ref:`line-too-long` warning configurable by adding a regex for lines
   for with the length limit should not be enforced
 
 * Do not warn about a long line if a pylint disable
@@ -81,7 +81,7 @@ Release date: 2013-08-06
 * Added a new warning 'old-raise-syntax' for the deprecated syntax
   raise Exception, args
 
-* Support for PEP 3102 and new missing-kwoa (E1125) message for missing
+* Support for PEP 3102 and new :ref:`missing-kwoa` (E1125) message for missing
   mandatory keyword argument
 
   Closes Logilab #107788

doc/whatsnew/1/1.1.rst

@@ -5,18 +5,18 @@
 Release date: 2013-12-22
 
 * Add new check for use of deprecated pragma directives "pylint:disable-msg"
-  or "pylint:enable-msg" (I0022, deprecated-pragma) which was previously
+  or "pylint:enable-msg" (I0022, :ref:`deprecated-pragma`) which was previously
   emitted as a regular warn().
 
-* Avoid false used-before-assignment for except handler defined
+* Avoid false :ref:`used-before-assignment` for except handler defined
   identifier used on the same line.
 
   Closes #111
 
 * Combine 'no-space-after-operator', 'no-space-after-comma' and
   'no-space-before-operator' into a new warning 'bad-whitespace'.
 
-* Add a new warning 'superfluous-parens' for unnecessary
+* Add a new warning ':ref:`superfluous-parens`' for unnecessary
   parentheses after certain keywords.
 
 * Fix a potential crash in the redefine-in-handler warning
@@ -25,7 +25,7 @@ Release date: 2013-12-22
 * Add a new option for the multi-statement warning to
   allow single-line if statements.
 
-* Add 'bad-context-manager' error, checking that '__exit__'
+* Add ':ref:`bad-context-manager`' error, checking that '__exit__'
   special method accepts the right number of arguments.
 
 * Run pylint as a python module 'python -m pylint' (Anatoly Techtonik).
@@ -39,14 +39,14 @@ Release date: 2013-12-22
   Closes BitBucket #53
   Closes BitBucket #54
 
-* Added a new warning, 'non-iterator-returned', for non-iterators
+* Added a new warning, ':ref:`non-iterator-returned`', for non-iterators
   returned by '__iter__'.
 
 * Add new checks for unpacking non-sequences in assignments
-  (unpacking-non-sequence) as well as unbalanced tuple unpacking
-  (unbalanced-tuple-unpacking).
+  (:ref:`unpacking-non-sequence`) as well as unbalanced tuple unpacking
+  (:ref:`unbalanced-tuple-unpacking`).
 
-* useless-else-on-loop not emitted if there is a break in the
+* :ref:`useless-else-on-loop` not emitted if there is a break in the
   else clause of inner loop.
 
   Closes #117
@@ -70,6 +70,6 @@ Release date: 2013-12-22
 
 * Various documentation fixes and enhancements
 
-* Fix a false-positive trailing-whitespace on Windows
+* Fix a false-positive :ref:`trailing-whitespace` on Windows
 
   Closes #55

doc/whatsnew/1/1.2.rst

@@ -10,7 +10,7 @@ Release date: 2014-04-30
 * Add a new warning [bad-continuation] for badly indented continued
   lines.
 
-* Emit [assignment-from-none] when the function contains bare returns.
+* Emit [:ref:`assignment-from-none`] when the function contains bare returns.
 
   Closes BitBucket #191
 
@@ -24,8 +24,8 @@ Release date: 2014-04-30
 
   Closes BitBucket #151
 
-* Extend the checking for unbalanced-tuple-unpacking and
-  unpacking-non-sequence to instance attribute unpacking as well.
+* Extend the checking for :ref:`unbalanced-tuple-unpacking` and
+  :ref:`unpacking-non-sequence` to instance attribute unpacking as well.
 
 * Fix explicit checking of python script (1.2 regression)
 
@@ -66,7 +66,7 @@ Release date: 2014-04-18
 
   Closes BitBucket #170
 
-* Add new warning 'eval-used', checking that the builtin function ``eval`` was used.
+* Add new warning ':ref:`eval-used`', checking that the builtin function ``eval`` was used.
 
 * Make it possible to show a naming hint for invalid name by setting
   include-naming-hint. Also make the naming hints configurable.
@@ -84,7 +84,7 @@ Release date: 2014-04-18
   warnings; contributed by [email protected].
 
 * Added a new configuration option logging-modules to make the list
-  of module names that can be checked for 'logging-not-lazy' et. al.
+  of module names that can be checked for ':ref:`logging-not-lazy`' et. al.
   configurable; contributed by [email protected].
 
 * ensure init-hooks is evaluated before other options, notably load-plugins
@@ -97,11 +97,11 @@ Release date: 2014-04-18
   Closes BitBucket #50
   Closes BitBucket #62
 
-* pylint doesn't crash when looking for used-before-assignment in context manager assignments.
+* pylint doesn't crash when looking for :ref:`used-before-assignment` in context manager assignments.
 
   Closes BitBucket #128
 
-* Add new warning, 'bad-reversed-sequence', for checking that the
+* Add new warning, ':ref:`bad-reversed-sequence`', for checking that the
   reversed() builtin receive a sequence (implements ``__getitem__`` and ``__len__``,
   without being a dict or a dict subclass) or an instance which implements
   ``__reversed__``.
@@ -110,25 +110,25 @@ Release date: 2014-04-18
 
   Closes #8
 
-* Add new warning 'bad-exception-context', checking
+* Add new warning ':ref:`bad-exception-context`', checking
   that ``raise ... from ...`` uses a proper exception context
   (None or an exception).
 
-* Enhance the check for 'used-before-assignment' to look
+* Enhance the check for ':ref:`used-before-assignment`' to look
   for 'nonlocal' uses.
 
-* Emit 'undefined-all-variable' if a package's __all__
+* Emit ':ref:`undefined-all-variable`' if a package's __all__
   variable contains a missing submodule.
 
   Closes #126
 
-* Add a new warning 'abstract-class-instantiated' for checking
+* Add a new warning ':ref:`abstract-class-instantiated`' for checking
   that abstract classes created with ``abc`` module and
   with abstract methods are instantiated.
 
-* Do not warn about 'return-arg-in-generator' in Python 3.3+.
+* Do not warn about ':ref:`return-arg-in-generator`' in Python 3.3+.
 
-* Do not warn about 'abstract-method' when the abstract method
+* Do not warn about ':ref:`abstract-method`' when the abstract method
   is implemented through assignment
 
   Closes #155
@@ -145,11 +145,11 @@ Release date: 2014-04-18
 
 * Don't register the new style checker w/ python >= 3
 
-* Fix unused-import false positive w/ augment assignment
+* Fix :ref:`unused-import` false positive w/ augment assignment
 
   Closes #78
 
-* Fix access-member-before-definition false negative wrt aug assign
+* Fix :ref:`access-member-before-definition` false negative wrt aug assign
 
   Closes #164
 

doc/whatsnew/1/1.3.rst

@@ -21,7 +21,7 @@ Release date: 2014-07-26
 
   Closes #205.
 
-* Emit 'undefined-variable' for undefined names when using the
+* Emit ':ref:`undefined-variable`' for undefined names when using the
   Python 3 ``metaclass=`` argument.
 
 * Checkers respect priority now.
@@ -32,29 +32,29 @@ Release date: 2014-07-26
 
   Closes #149.
 
-* Fix unused-import false positive with Python 3 metaclasses
+* Fix :ref:`unused-import` false positive with Python 3 metaclasses
 
   Closes #143
 
-* Don't warn with 'bad-format-character' when encountering
+* Don't warn with ':ref:`bad-format-character`' when encountering
   the 'a' format on Python 3.
 
 * Add multiple checks for PEP 3101 advanced string formatting:
-  'bad-format-string', 'missing-format-argument-key',
-  'unused-format-string-argument', 'format-combined-specification',
-  'missing-format-attribute' and 'invalid-format-index'.
+  ':ref:`bad-format-string`', ':ref:`missing-format-argument-key`',
+  ':ref:`unused-format-string-argument`', ':ref:`format-combined-specification`',
+  ':ref:`missing-format-attribute`' and ':ref:`invalid-format-index`'.
 
-* Issue broad-except and bare-except even if the number
+* Issue :ref:`broad-except` and :ref:`bare-except` even if the number
   of except handlers is different than 1.
 
   Closes #113
 
-* Issue attribute-defined-outside-init for all cases, not just
+* Issue :ref:`attribute-defined-outside-init` for all cases, not just
   for the last assignment.
 
   Closes #262
 
-* Emit 'not-callable' when calling properties.
+* Emit ':ref:`not-callable`' when calling properties.
 
   Closes #268.
 
@@ -63,17 +63,17 @@ Release date: 2014-07-26
 
   Closes #273.
 
-* Add new checks, 'invalid-slice-index' and 'invalid-sequence-index'
+* Add new checks, ':ref:`invalid-slice-index`' and ':ref:`invalid-sequence-index`'
   for invalid sequence and slice indices.
 
-* Add 'assigning-non-slot' warning, which detects assignments to
+* Add ':ref:`assigning-non-slot`' warning, which detects assignments to
   attributes not defined in slots.
 
-* Don't emit 'no-name-in-module' for ignored modules.
+* Don't emit ':ref:`no-name-in-module`' for ignored modules.
 
   Closes #223.
 
-* Fix an 'unused-variable' false positive, where the variable is
+* Fix an ':ref:`unused-variable`' false positive, where the variable is
   assigned through an import.
 
   Closes #196.
@@ -83,7 +83,7 @@ Release date: 2014-07-26
 
   Closes #257.
 
-* Don't emit 'unused-variable' when assigning to a nonlocal.
+* Don't emit ':ref:`unused-variable`' when assigning to a nonlocal.
 
   Closes #275.
 
@@ -92,7 +92,7 @@ Release date: 2014-07-26
 
   Closes #203.
 
-* Don't emit 'pointless-string-statement' for attribute docstrings.
+* Don't emit ':ref:`pointless-string-statement`' for attribute docstrings.
 
   Closes #193.
 
@@ -103,14 +103,14 @@ Release date: 2014-07-26
 * Don't emit hidden-method message when the attribute has been
   monkey-patched, you're on your own when you do that.
 
-* Only emit attribute-defined-outside-init for definition within the same
+* Only emit :ref:`attribute-defined-outside-init` for definition within the same
   module as the offended class, avoiding to mangle the output in some cases.
 
-* Don't emit 'unnecessary-lambda' if the body of the lambda call contains
+* Don't emit ':ref:`unnecessary-lambda`' if the body of the lambda call contains
   call chaining.
 
   Closes #243.
 
-* Don't emit 'missing-docstring' when the actual docstring uses ``.format``.
+* Don't emit ':ref:`missing-docstring`' when the actual docstring uses ``.format``.
 
   Closes #281.