[doc] Activate the nitpicky option in sphinx build (#6650)

This will warn about all missing references

* Remove references that don't work

Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com>

doc/Makefile

@@ -13,7 +13,7 @@ PYTHONPATH    =
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees -T -W --keep-going $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees -T -W --keep-going $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -n .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck
 

doc/development_guide/contribute.rst

@@ -71,9 +71,9 @@ Tips for Getting Started with Pylint Development
   codebase and will help you identify where you will need to make changes
   for what you are trying to implement.
 
-* :func:`astroid.extract_node` is your friend. Most checkers are AST based,
-  so you will likely need to interact with :mod:`astroid`.
-  A short example of how to use :func:`astroid.extract_node` is given
+* ``astroid.extract_node`` is your friend. Most checkers are AST based,
+  so you will likely need to interact with ``astroid``.
+  A short example of how to use ``astroid.extract_node`` is given
   :ref:`here <astroid_extract_node>`.
 
 * When fixing a bug for a specific check, search the code for the warning

doc/how_tos/custom_checkers.rst

@@ -18,9 +18,9 @@ There are three kinds of checkers:
   represent the source code in the file.
 * AST checkers, which work on an AST representation of the module.
 
-The AST representation is provided by the :mod:`astroid` library.
-:mod:`astroid` adds additional information and methods
-over :mod:`ast` in the standard library,
+The AST representation is provided by the ``astroid`` library.
+``astroid`` adds additional information and methods
+over ``ast`` in the standard library,
 to make tree navigation and code introspection easier.
 
 .. TODO Writing a Raw Checker
@@ -113,7 +113,7 @@ It has the following format::
 * The ``option-symbol`` is a unique name for the option.
   This is used on the command line and in config files.
   The hyphen is replaced by an underscore when used in the checker,
-  similarly to how you would use  :class:`argparse.Namespace`.
+  similarly to how you would use  ``argparse.Namespace``.
 
 Next we'll track when we enter and leave a function.
 
@@ -140,14 +140,14 @@ and to remove the list of return nodes when we leave the function.
 
 Finally we'll implement the check.
 We will define a ``visit_return`` function,
-which is called with an :class:`.astroid.nodes.Return` node.
+which is called with an ``.astroid.nodes.Return`` node.
 
 .. _astroid_extract_node:
 .. TODO We can shorten/remove this bit once astroid has API docs.
 
 We'll need to be able to figure out what attributes an
-:class:`.astroid.nodes.Return` node has available.
-We can use :func:`astroid.extract_node` for this::
+``.astroid.nodes.Return` node has available.
+We can use ``astroid.extract_node`` for this::
 
   >>> node = astroid.extract_node("return 5")
   >>> node
@@ -171,9 +171,9 @@ We could also construct a more complete example::
   >>> node_a.value.value == node_b.value.value
   True
 
-For :func:`astroid.extract_node`, you can use ``#@`` at the end of a line to choose which statements will be extracted into nodes.
+For ``astroid.extract_node``, you can use ``#@`` at the end of a line to choose which statements will be extracted into nodes.
 
-For more information on :func:`astroid.extract_node`,
+For more information on ``astroid.extract_node``,
 see the `astroid documentation <https://pylint.pycqa.org/projects/astroid/en/latest/>`_.
 
 Now we know how to use the astroid node, we can implement our check.
@@ -192,7 +192,7 @@ Now we know how to use the astroid node, we can implement our check.
       self._function_stack[-1].append(node)
 
 Once we have established that the source code has failed our check,
-we use :func:`~.BaseChecker.add_message` to emit our failure message.
+we use ``~.BaseChecker.add_message`` to emit our failure message.
 
 Finally, we need to register the checker with pylint.
 Add the ``register`` function to the top level of the file.
@@ -209,7 +209,7 @@ We are now ready to debug and test our checker!
 
 Debugging a Checker
 -------------------
-It is very simple to get to a point where we can use :mod:`pdb`.
+It is very simple to get to a point where we can use ``pdb``.
 We'll need a small test case.
 Put the following into a Python file:
 
@@ -260,7 +260,7 @@ produce all of your test cases and check that they fail,
 implement the checker,
 then check that all of your test cases work.
 
-Pylint provides a :class:`pylint.testutils.CheckerTestCase`
+Pylint provides a ``pylint.testutils.CheckerTestCase``
 to make test cases very simple.
 We can use the example code that we used for debugging as our test cases.
 
@@ -305,8 +305,8 @@ We can use the example code that we used for debugging as our test cases.
               self.checker.visit_return(return_node_b)
 
 
-Once again we are using :func:`astroid.extract_node` to
+Once again we are using ``astroid.extract_node`` to
 construct our test cases.
-:class:`pylint.testutils.CheckerTestCase` has created the linter and checker for us,
+``pylint.testutils.CheckerTestCase`` has created the linter and checker for us,
 we simply simulate a traversal of the AST tree
 using the nodes that we are interested in.

doc/make.bat

@@ -6,7 +6,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees -T -E -W --keep-going .
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees -T -E -W --keep-going -n .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
 )

doc/technical_reference/checkers.rst

@@ -2,6 +2,6 @@ Checkers
 --------
 All of the default pylint checkers exist in ``pylint.checkers``.
 This is where most of pylint's brains exist.
-Most checkers are AST based and so use :mod:`astroid`.
+Most checkers are AST based and so use ``astroid``.
 ``pylint.checkers.utils`` provides a large number of utility methods for
-dealing with :mod:`astroid`.
+dealing with ``astroid``.

doc/technical_reference/startup.rst

@@ -1,21 +1,21 @@
 Startup and the Linter Class
 ----------------------------
 
-The two main classes in :mod:`pylint.lint` are
-:class:`.pylint.lint.Run` and :class:`.pylint.lint.PyLinter`.
+The two main classes in ``pylint.lint`` are
+``.pylint.lint.Run`` and ``.pylint.lint.PyLinter``.
 
-The :class:`.pylint.lint.Run` object is responsible for starting up pylint.
+The ``.pylint.lint.Run`` object is responsible for starting up pylint.
 It does some basic checking of the given command line options to
 find the initial hook to run,
 find the config file to use,
 and find which plugins have been specified.
-It can then create the main :class:`.pylint.lint.PyLinter` instance
+It can then create the main ``.pylint.lint.PyLinter`` instance
 and initialise it with the config file and plugins that were discovered
 when preprocessing the command line options.
-Finally the :class:`.pylint.lint.Run` object launches any child linters
+Finally the ``.pylint.lint.Run`` object launches any child linters
 for parallel jobs, and starts the linting process.
 
-The :class:`.pylint.lint.PyLinter` is responsible for coordinating the
+The ``.pylint.lint.PyLinter`` is responsible for coordinating the
 linting process.
 It parses the configuration and provides it for the checkers and other plugins,
 it handles the messages emitted by the checkers,

doc/whatsnew/2.0.rst

@@ -224,7 +224,7 @@ Other Changes
 * A couple of performance improvements brought to ``astroid`` should make
   ``pylint`` should be a bit faster as well.
 
-  We added a new flag, ``max_inferable_values`` on :class:`astroid.MANAGER` for
+  We added a new flag, ``max_inferable_values`` on ``astroid.MANAGER`` for
   limitting the maximum amount of values that ``astroid`` can infer when inferring
   values. This change should improve the performance when dealing with large frameworks
   such as ``django``.

doc/whatsnew/2.2.rst

@@ -46,7 +46,7 @@ Other Changes
 
 * Fix false positive ``undefined-variable`` and ``used-before-assignment`` with nonlocal keyword usage.
 
-* Fix exceptions being raised when one of the params is not a ClassDef for :func:`checkers.utils.is_subclass_of`.
+* Fix exceptions being raised when one of the params is not a ClassDef for ``checkers.utils.is_subclass_of``.
 
 * ``pylint`` now picks the latest value from the inferred values of the exception that gets
   raised, when looking for ``raising-non-exception``. This helps when reusing a variable name