Enable 'nit-picky mode' for Sphinx's documentation

Fix several reference errors throughout the documentation and set
``nitpick_ignore`` in ``doc/conf.py``.

.github/workflows/builddoc.yml

@@ -33,4 +33,5 @@ jobs:
         -m sphinx
         -M html ./doc ./build/sphinx
         -W
+        -n
         --keep-going

CHANGES

@@ -489,7 +489,7 @@ Bugs fixed
 
 * #10498: gettext: TypeError is raised when sorting warning messages if a node
   has no line number. Patch by Adam Turner.
-* #10493: HTML Theme: :rst:dir:`topic` directive is rendered incorrectly with
+* #10493: HTML Theme: :dudir:`topic` directive is rendered incorrectly with
   Docutils 0.18. Patch by Adam Turner.
 * #10495: IndexError is raised for a :rst:role:`kbd` role having a separator.
   Patch by Adam Turner.
@@ -593,7 +593,7 @@ Features added
   underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
   EMCAScript 2018. Patch by Adam Turner.
 * #10302: C++, add support for conditional expressions (``?:``).
-* #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role`
+* #5157, #10251: Inline code is able to be highlighted via :dudir:`role`
   directive
 * #10337: Make sphinx-build faster by caching Publisher object during build.
   Patch by Adam Turner.
@@ -916,7 +916,7 @@ Bugs fixed
 * #9697: py domain: An index entry with parens was registered for ``py:method``
   directive with ``:property:`` option
 * #9775: py domain: Literal typehint was converted to a cross reference when
-  :confval:`autodoc_typehints='description'`
+  :confval:`autodoc_typehints`\ ``='description'``
 * #9708: needs_extension failed to check double-digit version correctly
 * #9688: Fix Sphinx patched :dudir:`code` does not recognize ``:class:`` option
 * #9733: Fix for logging handler flushing warnings in the middle of the docs
@@ -1209,7 +1209,8 @@ Incompatible changes
 4.0.0b1
 
 * #8539: autodoc: info-field-list is generated into the class description when
-  ``autodoc_typehints='description'`` and ``autoclass_content='class'`` set
+  :confval:`autodoc_typehints`\ ``='description'`` and
+  :confval:`autoclass_content`\ ``='class'`` set
 * #8898: extlinks: "%s" becomes required keyword in the link caption string
 * domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate
   methods that must be overridden in the concrete classes
@@ -1471,7 +1472,7 @@ Features added
   functions in source code and keep them not evaluated for readability.
 * #8619: html: kbd role generates customizable HTML tags for compound keys
 * #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter
-  for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()`
+  for :meth:`.Sphinx.add_js_file()` and :meth:`.Sphinx.add_css_file()`
 * #6241: html: Allow to add JS/CSS files to the specific page when an extension
   calls ``app.add_js_file()`` or ``app.add_css_file()`` on
   :event:`html-page-context` event
@@ -1485,7 +1486,7 @@ Features added
 * #8649: imgconverter: Skip availability check if builder supports the image
   type
 * #8573: napoleon: Allow to change the style of custom sections using
-  :confval:`napoleon_custom_styles`
+  :confval:`napoleon_custom_sections`
 * #8004: napoleon: Type definitions in Google style docstrings are rendered as
   references when :confval:`napoleon_preprocess_types` enabled
 * #6241: mathjax: Include mathjax.js only on the document using equations
@@ -1672,7 +1673,7 @@ Features added
   messages when failed to resolve a cross-reference
 * #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference
 * #6629: linkcheck: The builder now handles rate limits. See
-  :confval:`linkcheck_retry_on_rate_limit` for details.
+  :confval:`linkcheck_rate_limit_timeout` for details.
 
 Bugs fixed
 ----------
@@ -1855,7 +1856,7 @@ Deprecated
 * ``sphinx.ext.autodoc.merge_special_members_option()``
 * ``sphinx.writers.texinfo.TexinfoWriter.desc``
 * C, parsing of pre-v3 style type directives and roles, along with the options
-  :confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`.
+  :confval:`!c_allow_pre_v3` and :confval:`!c_warn_on_allowed_pre_v3`.
 
 Features added
 --------------
@@ -1874,7 +1875,7 @@ Features added
 * #7690: napoleon: parse type strings and make them hyperlinks as possible.  The
   conversion rule can be updated via :confval:`napoleon_type_aliases`
 * #8049: napoleon: Create a hyperlink for each the type of parameter when
-  :confval:`napoleon_use_params` is False
+  :confval:`napoleon_use_param` is False
 * C, added :rst:dir:`c:alias` directive for inserting copies
   of existing declarations.
 * #7745: html: inventory is broken if the docname contains a space
@@ -1892,9 +1893,9 @@ Features added
   and the ``:noindex:`` option.
 * #7899: C, add possibility of parsing of some pre-v3 style type directives and
   roles and try to convert them to equivalent v3 directives/roles.
-  Set the new option :confval:`c_allow_pre_v3` to ``True`` to enable this.
+  Set the new option :confval:`!c_allow_pre_v3` to ``True`` to enable this.
   The warnings printed from this functionality can be suppressed by setting
-  :confval:`c_warn_on_allowed_pre_v3`` to ``True``.
+  :confval:`!c_warn_on_allowed_pre_v3` to ``True``.
   The functionality is immediately deprecated.
 * #7999: C, add support for named variadic macro arguments.
 * #8071: Allow to suppress "self referenced toctrees" warning
@@ -1925,7 +1926,7 @@ Bugs fixed
 * #4258: napoleon: decorated special methods are not shown
 * #7799: napoleon: parameters are not escaped for combined params in numpydoc
 * #7780: napoleon: multiple parameters declaration in numpydoc was wrongly
-  recognized when napoleon_use_params=True
+  recognized when ``napoleon_use_param=True``
 * #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links
 * #7846: html theme: XML-invalid files were generated
 * #7894: gettext: Wrong source info is shown when using rst_epilog
@@ -2093,8 +2094,8 @@ Features added
 * C++, parse parameterized noexcept specifiers.
 * #7294: C++, parse expressions with user-defined literals.
 * C++, parse trailing return types.
-* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class:`,
+* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class`,
-  :rst:dir:`py:exception:` and :rst:dir:`py:method:` directives
+  :rst:dir:`py:exception` and :rst:dir:`py:method` directives
 * #7596: py domain: Change a type annotation for variables to a hyperlink
 * #7770: std domain: :rst:dir:`option` directive support arguments in the form
   of ``foo[=bar]``
@@ -2118,7 +2119,7 @@ Bugs fixed
 * #7559: autodoc: misdetects a sync function is async
 * #6857: autodoc: failed to detect a classmethod on Enum class
 * #7562: autodoc: a typehint contains spaces is wrongly rendered under
-  autodoc_typehints='description' mode
+  :confval:`autodoc_typehints`\ ``='description'`` mode
 * #7551: autodoc: failed to import nested class
 * #7362: autodoc: does not render correct signatures for built-in functions
 * #7654: autodoc: ``Optional[Union[foo, bar]]`` is presented as
@@ -2221,7 +2222,7 @@ Release 3.0.1 (released Apr 11, 2020)
 Incompatible changes
 --------------------
 
-* #7418: std domain: :rst:dir:`term` role becomes case sensitive
+* #7418: std domain: :rst:role:`term` role becomes case sensitive
 
 Bugs fixed
 ----------
@@ -2232,8 +2233,8 @@ Bugs fixed
 * #7418: std domain: duplication warning for glossary terms is case insensitive
 * #7438: C++, fix merging overloaded functions in parallel builds.
 * #7422: autodoc: fails with ValueError when using autodoc_mock_imports
-* #7435: autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints
+* #7435: autodoc: :confval:`autodoc_typehints`\ ``='description'`` doesn't
-  in signature for classes/methods
+  suppress typehints in signature for classes/methods
 * #7451: autodoc: fails with AttributeError when an object returns non-string
   object as a ``__doc__`` member
 * #7423: crashed when giving a non-string object to logger
@@ -2644,7 +2645,7 @@ Features added
   authentication information when doing ``linkcheck`` builds
 * #6872: linkcheck: Handles HTTP 308 Permanent Redirect
 * #6613: html: Wrap section number in span tag
-* #6781: gettext: Add :confval:`gettext_last_translator' and
+* #6781: gettext: Add :confval:`gettext_last_translator` and
   :confval:`gettext_language_team` to customize headers of POT file
 
 Bugs fixed
@@ -2783,7 +2784,7 @@ Bugs fixed
   since Sphinx 1.8.0 (refs: #6533)
 * #6531: Failed to load last environment object when extension added
 * #736: Invalid sort in pair index
-* #6527: :confval:`last_updated` wrongly assumes timezone as UTC
+* #6527: :data:`last_updated` wrongly assumes timezone as UTC
 * #5592: std domain: :rst:dir:`option` directive registers an index entry for
   each comma separated option
 * #6549: sphinx-build: Escaped characters in error messages
@@ -2898,7 +2899,7 @@ Features added
   - ``PythonDomain.note_object()``
   - ``SphinxDirective.set_source_info()``
 
-* #6180: Support ``--keep-going`` with BuildDoc setup command
+* #6180: Support ``--keep-going`` with ``BuildDoc`` setup command
 * ``math`` directive now supports ``:class:`` option
 * todo: ``todo`` directive now supports ``:name:`` option
 * Enable override via environment of ``SPHINXOPTS`` and ``SPHINXBUILD`` Makefile
@@ -2928,7 +2929,7 @@ Features added
   - ``:property:``
   - ``:staticmethod:``
 
-* rst domain: Add :rst:dir:`directive:option` directive to describe the option
+* rst domain: Add :rst:dir:`rst:directive:option` directive to describe the option
   for directive
 * #6306: html: Add a label to search form for accessability purposes
 * #4390: html: Consistent and semantic CSS for signatures
@@ -2975,9 +2976,9 @@ Bugs fixed
 * RemovedInSphinx30Warning is marked as pending
 * deprecation warnings are not emitted
 
-  - sphinx.application.CONFIG_FILENAME
+  - ``sphinx.application.CONFIG_FILENAME``
-  - sphinx.builders.htmlhelp
+  - ``sphinx.builders.htmlhelp``
-  - :confval:`viewcode_import`
+  - :confval:`!viewcode_import`
 
 * #6208: C++, properly parse full xrefs that happen to have a short xref as
   prefix
@@ -3460,7 +3461,7 @@ Incompatible changes
 
 1.8.0b1
 
-* #5156: the :py:mod:`sphinx.ext.graphviz: extension runs `dot` in the
+* #5156: the :py:mod:`sphinx.ext.graphviz` extension runs ``dot`` in the
   directory of the document being built instead of in the root directory of
   the documentation.
 * #4460: extensions which stores any data to environment should return the
@@ -3485,7 +3486,7 @@ Incompatible changes
 * #4811: The files under :confval:`html_static_path` are excluded from source
   files.
 * latex: Use ``\sphinxcite`` for citation references instead ``\hyperref``
-* The config value ``viewcode_import`` is renamed to
+* The config value :confval:`!viewcode_import` is renamed to
   :confval:`viewcode_follow_imported_members` (refs: #4035)
 * #1857: latex: :confval:`latex_show_pagerefs` does not add pagerefs for
   citations
@@ -3526,7 +3527,7 @@ Deprecated
 * :confval:`autodoc_default_flags` is deprecated
 * quickstart: ``--epub`` option becomes default, so it is deprecated
 * Drop function based directive support.  For now, Sphinx only supports class
-  based directives (see :class:`~Directive`)
+  based directives (see :class:`~docutils.parsers.rst.Directive`)
 * ``sphinx.util.docutils.directive_helper()`` is deprecated
 * ``sphinx.cmdline`` is deprecated
 * ``sphinx.make_mode`` is deprecated
@@ -4102,8 +4103,8 @@ Features removed
 
 * Configuration variables
 
-  - html_use_smartypants
+  - :confval:`!html_use_smartypants`
-  - latex_keep_old_macro_names
+  - :confval:`!latex_keep_old_macro_names`
   - latex_elements['footer']
 
 * utility methods of ``sphinx.application.Sphinx`` class
@@ -4429,7 +4430,7 @@ Incompatible changes
   option and other options (refs: #3416)
 * LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine
   = 'lualatex'`` be used only on up-to-date TeX installs (refs #3070, #3466)
-* :confval:`latex_keep_old_macro_names` default value has been changed from
+* :confval:`!latex_keep_old_macro_names` default value has been changed from
   ``True`` to ``False``. This means that some LaTeX macros for styling are
   by default defined only with ``\sphinx..`` prefixed names. (refs: #3429)
 * Footer "Continued on next page" of LaTeX longtable's now not framed (refs:
@@ -4635,8 +4636,8 @@ Deprecated
 * latex package  ``footnote`` is not loaded anymore by its bundled replacement
   ``footnotehyper-sphinx``. The redefined macros keep the same names as in the
   original package.
-* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be
+* #3429: deprecate config setting :confval:`!latex_keep_old_macro_names`. It will
-  removed at 1.7, and already its default value has changed from ``True`` to
+  be removed at 1.7, and already its default value has changed from ``True`` to
   ``False``.
 * #3221: epub2 builder is deprecated
 * #3254: ``sphinx.websupport`` is now separated into independent package;
@@ -4902,7 +4903,7 @@ Incompatible changes
 * Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even
   if ``epub_use_index = False``.
 * ``html_translator_class`` is now deprecated.
-  Use `Sphinx.set_translator()` API instead.
+  Use :meth:`~sphinx.application.Sphinx.set_translator` API instead.
 * Drop python 2.6 and 3.3 support
 * Drop epub3 builder's ``epub3_page_progression_direction`` option (use
   ``epub3_writing_mode``).
@@ -5261,7 +5262,7 @@ Incompatible changes
 Features added
 --------------
 
-* new config option ``latex_keep_old_macro_names``, defaults to True. If False,
+* new config option :confval:`!latex_keep_old_macro_names`, defaults to True. If False,
   lets macros (for text styling) be defined only with ``\sphinx``-prefixed names
 * latex writer allows user customization of "shadowed" boxes (topics), via
   three length variables.
@@ -6649,7 +6650,8 @@ Features added
 * Other builders:
 
   - Added the Docutils-native XML and pseudo-XML builders.  See
-    :class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
+    :class:`~sphinx.builders.xml.XMLBuilder` and
+    :class:`~sphinx.builders.xml.PseudoXMLBuilder`.
   - PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
   - PR#123, #1106: Add `epub_use_index` configuration value.  If
     provided, it will be used instead of `html_use_index` for epub
@@ -6916,26 +6918,26 @@ Features added
 
 * Other builders:
 
-  - #516: Added new value of the `latex_show_urls` option to
+  - #516: Added new value of the :confval:`latex_show_urls` option to
     show the URLs in footnotes.
-  - #209: Added `text_newlines` and `text_sectionchars`
+  - #209: Added :confval:`text_newlines` and :confval:`text_sectionchars`
     config values.
-  - Added `man_show_urls` config value.
+  - Added :confval:`man_show_urls` config value.
   - #472: linkcheck builder: Check links in parallel, use HTTP HEAD
     requests and allow configuring the timeout.  New config values:
-    `linkcheck_timeout` and `linkcheck_workers`.
+    :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`.
-  - #521: Added `linkcheck_ignore` config value.
+  - #521: Added :confval:`linkcheck_ignore` config value.
   - #28: Support row/colspans in tables in the LaTeX builder.
 
 * Configuration and extensibility:
 
-  - #537: Added `nitpick_ignore`.
+  - #537: Added :confval:`nitpick_ignore`.
   - #306: Added :event:`env-get-outdated` event.
-  - :meth:`.Application.add_stylesheet` now accepts full URIs.
+  - :meth:`!Application.add_stylesheet` now accepts full URIs.
 
 * Autodoc:
 
-  - #564: Add `autodoc_docstring_signature`.  When enabled (the
+  - #564: Add :confval:`autodoc_docstring_signature`.  When enabled (the
     default), autodoc retrieves the signature from the first line of the
     docstring, if it is found there.
   - #176: Provide ``private-members`` option for autodoc directives.
@@ -7195,7 +7197,7 @@ Release 1.0.2 (Aug 14, 2010)
 ============================
 
 * #490: Fix cross-references to objects of types added by the
-  :func:`~.Sphinx.add_object_type` API function.
+  :func:`~sphinx.application.Sphinx.add_object_type` API function.
 
 * Fix handling of doc field types for different directive types.
 
@@ -7267,7 +7269,7 @@ Incompatible changes
 
 * The old markup for defining and linking to C directives is now
   deprecated.  It will not work anymore in future versions without
-  activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx
+  activating the ``oldcmarkup`` extension; in Sphinx
   1.0, it is activated by default.
 
 * Removed support for old dependency versions; requirements are now:
@@ -7376,7 +7378,7 @@ Features added
   - Added `needs_sphinx` config value and
     :meth:`~sphinx.application.Sphinx.require_sphinx` application API
     method.
-  - #200: Added :meth:`~sphinx.application.Sphinx.add_stylesheet`
+  - #200: Added :meth:`!add_stylesheet`
     application API method.
 
 * Extensions:
@@ -8030,7 +8032,7 @@ New features added
   - Highlighted code blocks now have CSS classes that make it possible
     to style them depending on their language.
 
-  - HTML ``<meta>`` tags via the docutils ``meta`` directive are now
+  - HTML ``<meta>`` tags via the docutils :dudir:`meta` directive are now
     supported.
 
   - ``SerializingHTMLBuilder`` was added as new abstract builder that

doc/conf.py

@@ -121,6 +121,63 @@ intersphinx_mapping = {
 locale_dirs = ['locale/']
 gettext_compact = False
 
+nitpick_ignore = {
+    ('cpp:class', 'template<typename TOuter> template<typename TInner> Wrapper::Outer<TOuter>::Inner'),  # NoQA: E501
+    ('cpp:identifier', 'MyContainer'),
+    ('js:func', 'SomeError'),
+    ('js:func', 'number'),
+    ('js:func', 'string'),
+    ('py:attr', 'srcline'),
+    ('py:class', 'Element'),  # sphinx.domains.Domain
+    ('py:class', 'Node'),  # sphinx.domains.Domain
+    ('py:class', 'RoleFunction'),  # sphinx.domains.Domain
+    ('py:class', 'Theme'),  # sphinx.application.TemplateBridge
+    ('py:class', 'TitleGetter'),  # sphinx.domains.Domain
+    ('py:class', 'XRefRole'),  # sphinx.domains.Domain
+    ('py:class', 'docutils.nodes.Element'),
+    ('py:class', 'docutils.nodes.Node'),
+    ('py:class', 'docutils.nodes.NodeVisitor'),
+    ('py:class', 'docutils.nodes.TextElement'),
+    ('py:class', 'docutils.nodes.document'),
+    ('py:class', 'docutils.nodes.system_message'),
+    ('py:class', 'docutils.parsers.Parser'),
+    ('py:class', 'docutils.parsers.rst.states.Inliner'),
+    ('py:class', 'docutils.transforms.Transform'),
+    ('py:class', 'nodes.NodeVisitor'),
+    ('py:class', 'nodes.document'),
+    ('py:class', 'nodes.reference'),
+    ('py:class', 'pygments.lexer.Lexer'),
+    ('py:class', 'sphinx.directives.ObjDescT'),
+    ('py:class', 'sphinx.domains.IndexEntry'),
+    ('py:class', 'sphinx.ext.autodoc.Documenter'),
+    ('py:class', 'sphinx.errors.NoUri'),
+    ('py:class', 'sphinx.roles.XRefRole'),
+    ('py:class', 'sphinx.search.SearchLanguage'),
+    ('py:class', 'sphinx.theming.Theme'),
+    ('py:class', 'sphinxcontrib.websupport.errors.DocumentNotFoundError'),
+    ('py:class', 'sphinxcontrib.websupport.errors.UserNotAuthorizedError'),
+    ('py:exc', 'docutils.nodes.SkipNode'),
+    ('py:exc', 'sphinx.environment.NoUri'),
+    ('py:func', 'setup'),
+    ('py:func', 'sphinx.util.nodes.nested_parse_with_titles'),
+    # Error in sphinxcontrib.websupport.core::WebSupport.add_comment
+    ('py:meth', 'get_comments'),
+    ('py:mod', 'autodoc'),
+    ('py:mod', 'docutils.nodes'),
+    ('py:mod', 'docutils.parsers.rst.directives'),
+    ('py:mod', 'sphinx.ext'),
+    ('py:obj', 'sphinx.util.relative_uri'),
+    ('rst:role', 'c:any'),
+    ('std:confval', 'autodoc_inherit_docstring'),
+    ('std:confval', 'automodule_skip_lines'),
+    ('std:confval', 'autossummary_imported_members'),
+    ('std:confval', 'gettext_language_team'),
+    ('std:confval', 'gettext_last_translator'),
+    ('std:confval', 'globaltoc_collapse'),
+    ('std:confval', 'globaltoc_includehidden'),
+    ('std:confval', 'globaltoc_maxdepth'),
+}
+
 
 # -- Extension interface -------------------------------------------------------
 

doc/development/overview.rst

@@ -15,7 +15,7 @@ extension developer.
     :noindex:
 
 To ensure that another extension is activated as a part of your own extension,
-use the :meth:`Sphinx.setup_extension` method. This will
+use the :meth:`sphinx.application.Sphinx.setup_extension` method. This will
 activate another extension at run-time, ensuring that you have access to its
 functionality.
 

doc/development/templating.rst

@@ -26,9 +26,9 @@ No.  You have several other options:
   :class:`~sphinx.builders.html.StandaloneHTMLBuilder` and calls your template
   engine of choice.
 
-* You can use the :class:`~sphinx.builders.html.PickleHTMLBuilder` that produces
+* You can use the :class:`~sphinxcontrib.serializinghtml.PickleHTMLBuilder` that
-  pickle files with the page contents, and postprocess them using a custom tool,
+  produces pickle files with the page contents, and postprocess them using a
-  or use them in your Web application.
+  custom tool, or use them in your Web application.
 
 
 Jinja/Sphinx Templating Primer

doc/development/theming.rst

@@ -36,7 +36,7 @@ theme name), containing the following:
   output static directory on build.  These can be images, styles, script files.
 
 The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
-Python :mod:`ConfigParser` module) and has the following structure:
+Python :mod:`configparser` module) and has the following structure:
 
 .. sourcecode:: ini
 
@@ -69,7 +69,7 @@ Python :mod:`ConfigParser` module) and has the following structure:
 * The **pygments_dark_style** setting gives the name of a Pygments style to use
   for highlighting when the CSS media query ``(prefers-color-scheme: dark)``
   evaluates to true. It is injected into the page using
-  :meth:`~Sphinx.add_css_file()`.
+  :meth:`~sphinx.application.Sphinx.add_css_file()`.
 
 * The **sidebars** setting gives the comma separated list of sidebar templates
   for constructing sidebars.  This can be overridden by the user in the
@@ -306,7 +306,7 @@ Will result in the following static file placed in your HTML's build output:
 
 See :ref:`theming-static-templates` for more information.
 
-Second, you may use the :meth:`Sphinx.add_js_file` method without pointing it
+Second, you may use the :meth:`.Sphinx.add_js_file` method without pointing it
 to a file. Normally, this method is used to insert a new JavaScript file
 into your site. However, if you do *not* pass a file path, but instead pass
 a string to the "body" argument, then this text will be inserted as JavaScript

doc/development/tutorials/autodoc_ext.rst

@@ -54,9 +54,10 @@ Start with ``setup`` function for the extension.
    :pyobject: setup
 
 
-The :meth:`~Sphinx.setup_extension` method will pull the autodoc extension
+The :meth:`~sphinx.application.Sphinx.setup_extension` method will pull the
-because our new extension depends on autodoc. :meth:`~Sphinx.add_autodocumenter`
+autodoc extension because our new extension depends on autodoc.
-is the method that registers our new auto documenter class.
+:meth:`~sphinx.application.Sphinx.add_autodocumenter` is the method that
+registers our new auto documenter class.
 
 We want to import certain objects from the autodoc extension:
 

doc/development/tutorials/todo.rst

@@ -112,7 +112,7 @@ is just a "general" node.
 
    It is important to know that while you can extend Sphinx without
    leaving your ``conf.py``, if you declare an inherited node right
-   there, you'll hit an unobvious :py:class:`PickleError`. So if
+   there, you'll hit an unobvious :py:class:`~pickle.PickleError`. So if
    something goes wrong, please make sure that you put inherited nodes
    into a separate Python module.
 

doc/extdev/appapi.rst

@@ -278,16 +278,16 @@ Here is a more detailed list of these events.
    Emitted when a cross-reference to an object cannot be resolved.
    If the event handler can resolve the reference, it should return a
    new docutils node to be inserted in the document tree in place of the node
-   *node*.  Usually this node is a :class:`reference` node containing *contnode*
+   *node*.  Usually this node is a :class:`~nodes.reference` node containing
-   as a child.
+   *contnode* as a child.
    If the handler can not resolve the cross-reference,
    it can either return ``None`` to let other handlers try,
-   or raise :class:`NoUri` to prevent other handlers in trying and suppress
+   or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in
-   a warning about this cross-reference being unresolved.
+   trying and suppress a warning about this cross-reference being unresolved.
 
    :param env: The build environment (``app.builder.env``).
-   :param node: The :class:`pending_xref` node to be resolved.  Its attributes
+   :param node: The :class:`~sphinx.addnodes.pending_xref` node to be resolved.
-      ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
+      Its ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
       determine the type and target of the reference.
    :param contnode: The node that carries the text and formatting inside the
       future reference and should be a child of the returned reference node.
@@ -330,8 +330,8 @@ Here is a more detailed list of these events.
 
 .. event:: env-updated (app, env)
 
-   Emitted when the :meth:`update` method of the build environment has
+   Emitted after reading all documents, when the environment and all
-   completed, that is, the environment and all doctrees are now up-to-date.
+   doctrees are now up-to-date.
 
    You can return an iterable of docnames from the handler.  These documents
    will then be considered updated, and will be (re-)written during the writing

doc/extdev/deprecated.rst

@@ -1355,17 +1355,17 @@ The following is a list of deprecated interfaces.
      - 4.0
      - N/A
 
-   * - :rst:dir:`highlightlang`
+   * - :rst:dir:`!highlightlang`
      - 1.8
      - 4.0
      - :rst:dir:`highlight`
 
-   * - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+   * - :meth:`!add_stylesheet`
      - 1.8
      - 6.0
      - :meth:`~sphinx.application.Sphinx.add_css_file()`
 
-   * - :meth:`~sphinx.application.Sphinx.add_javascript()`
+   * - :meth:`!add_javascript()`
      - 1.8
      - 4.0
      - :meth:`~sphinx.application.Sphinx.add_js_file()`
@@ -1467,7 +1467,7 @@ The following is a list of deprecated interfaces.
      - 3.0
      - ``sphinx.builders.latex.nodes.math_reference``
 
-   * - ``viewcode_import`` (config value)
+   * - :confval:`!viewcode_import` (config value)
      - 1.8
      - 3.0
      - :confval:`viewcode_follow_imported_members`
@@ -1825,7 +1825,7 @@ The following is a list of deprecated interfaces.
    * - ``StandaloneHTMLBuilder.css_files``
      - 1.6
      - 2.0
-     - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+     - :meth:`!add_stylesheet`
 
    * - ``document.settings.gettext_compact``
      - 1.8

doc/extdev/markupapi.rst

@@ -63,7 +63,7 @@ using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`.
 
    .. attribute:: content
 
-      The directive content, if given, as a :class:`.ViewList`.
+      The directive content, if given, as a :class:`!ViewList`.
 
    .. attribute:: lineno
 

doc/glossary.rst

@@ -81,8 +81,8 @@ Glossary
 
    object
       The basic building block of Sphinx documentation.  Every "object
-      directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a
+      directive" (e.g. :rst:dir:`py:function` or :rst:dir:`object`) creates such
-      block; and most objects can be cross-referenced to.
+      a block; and most objects can be cross-referenced to.
 
    RemoveInSphinxXXXWarning
       The feature which is warned will be removed in Sphinx-XXX version.

doc/latex.rst

@@ -83,7 +83,7 @@ The ``latex_elements`` configuration setting
 A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
 into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
 :ref:`separately <latexsphinxsetup>`.  It allows also local configurations
-inserted in generated files, via :rst:dir:`raw` directives.  For example, in
+inserted in generated files, via :dudir:`raw` directives.  For example, in
 the PDF documentation this chapter is styled especially, as will be described
 later.
 

doc/man/sphinx-apidoc.rst

@@ -11,8 +11,8 @@ Description
 -----------
 
 :program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources
-that, using the :rst:dir:`autodoc` extension, document a whole package in the
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document a whole
-style of other automatic API documentation tools.
+package in the style of other automatic API documentation tools.
 
 *MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
 the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s

doc/man/sphinx-autogen.rst

@@ -10,8 +10,8 @@ Description
 -----------
 
 :program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
-that, using the :rst:dir:`autodoc` extension, document items included in
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included
-:rst:dir:`autosummary` listing(s).
+in :rst:dir:`autosummary` listing(s).
 
 *sourcefile* is the path to one or more reStructuredText documents containing
 :rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
@@ -88,8 +88,8 @@ then the following stub files will be created in ``docs``::
         ├── foobar.bar.baz.rst
         └── foobar.foo.rst
 
-and each of those files will contain a :rst:dir:`autodoc` directive and some
+and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive
-other information.
+and some other information.
 
 See also
 --------

doc/man/sphinx-quickstart.rst

@@ -78,7 +78,7 @@ Options
 
 .. option:: --ext-autodoc
 
-   Enable `sphinx.ext.autodoc` extension.
+   Enable :py:mod:`sphinx.ext.autodoc` extension.
 
 .. option:: --ext-doctest
 

doc/usage/advanced/setuptools.rst

@@ -4,11 +4,11 @@ Setuptools integration
 ======================
 
 Sphinx supports integration with setuptools and distutils through a custom
-command - :class:`~sphinx.setup_command.BuildDoc`.
+command - :class:`!sphinx.setup_command.BuildDoc`.
 
 .. deprecated:: 5.0
 
-   This feature will be removed in v7.0.
+   This feature will be removed in Sphinx 7.0.
 
 Using setuptools integration
 ----------------------------

doc/usage/advanced/websupport/quickstart.rst

@@ -252,4 +252,4 @@ class when instantiating your support object::
    support = WebSupport(..., moderation_callback=moderation_callback)
 
 The moderation callback must take one argument, which will be the same comment
-dict that is returned by :meth:`add_comment`.
+dict that is returned by :meth:`.WebSupport.add_comment`.

doc/usage/configuration.rst

@@ -307,7 +307,7 @@ General configuration
    "filter".  The default is ``None``, which doesn't reassign the default role.
 
    The default role can always be set within individual documents using the
-   standard reST :rst:dir:`default-role` directive.
+   standard reST :dudir:`default-role` directive.
 
    .. versionadded:: 0.4
 
@@ -440,12 +440,14 @@ General configuration
 
 .. confval:: nitpick_ignore
 
-   A list of ``(type, target)`` tuples (by default empty) that should be
+   A set or list of ``(type, target)`` tuples (by default empty) that should be
    ignored when generating warnings in "nitpicky mode".  Note that ``type``
    should include the domain name if present.  Example entries would be
    ``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``.
 
    .. versionadded:: 1.1
+   .. versionchanged:: 6.2
+      Changed allowable container types to a set, list, or tuple
 
 .. confval:: nitpick_ignore_regex
 
@@ -460,6 +462,8 @@ General configuration
    ``('py:class', 'food.bar.Barman')``.
 
    .. versionadded:: 4.1
+   .. versionchanged:: 6.2
+      Changed allowable container types to a set, list, or tuple
 
 .. confval:: numfig
 
@@ -1132,7 +1136,7 @@ that use Sphinx's HTMLWriter class.
 
    As a special attribute, *priority* can be set as an integer to load the CSS
    file earlier or lazier step.  For more information, refer
-   :meth:`Sphinx.add_css_files()`.
+   :meth:`.Sphinx.add_css_file()`.
 
    .. versionadded:: 1.8
    .. versionchanged:: 3.5
@@ -1155,7 +1159,7 @@ that use Sphinx's HTMLWriter class.
 
    As a special attribute, *priority* can be set as an integer to load the CSS
    file earlier or lazier step.  For more information, refer
-   :meth:`Sphinx.add_css_files()`.
+   :meth:`.Sphinx.add_css_file()`.
 
    .. versionadded:: 1.8
    .. versionchanged:: 3.5
@@ -1217,7 +1221,7 @@ that use Sphinx's HTMLWriter class.
 .. confval:: html_last_updated_fmt
 
    If this is not None, a 'Last updated on:' timestamp is inserted
-   at every page bottom, using the given :func:`strftime` format.
+   at every page bottom, using the given :func:`~time.strftime` format.
    The empty string is equivalent to ``'%b %d, %Y'`` (or a
    locale-dependent equivalent).
 
@@ -1480,8 +1484,8 @@ that use Sphinx's HTMLWriter class.
 
    :type:
       _`type` is dotted module path string to specify Splitter implementation
-      which should be derived from :class:`sphinx.search.ja.BaseSplitter`.  If
+      which should be derived from :class:`!sphinx.search.ja.BaseSplitter`.  If
-      not specified or None is specified,
+      not specified or ``None`` is specified,
       ``'sphinx.search.ja.DefaultSplitter'`` will be used.
 
       You can choose from these modules:
@@ -1732,7 +1736,7 @@ HTML builder, so the HTML options also apply where appropriate.
    Italian    it
    =========  ====
 
-   Defaults to :confval:`language`, or if that is not set, to :confval:`en`.
+   Defaults to :confval:`language`, or if that is not set, to ``'en'``.
 
 .. confval:: applehelp_locale
 
@@ -1740,7 +1744,7 @@ HTML builder, so the HTML options also apply where appropriate.
    the name of the ``.lproj`` folder inside the Help Book’s ``Resources``, and
    is passed to the help indexer.
 
-   Defaults to :confval:`language`, or if that is not set, to :confval:`en`.
+   Defaults to :confval:`language`, or if that is not set, to ``'en'``.
 
 .. confval:: applehelp_title
 

doc/usage/extensions/inheritance.rst

@@ -131,6 +131,11 @@ part (``sphinx``) from all names::
    :top-classes: sphinx.util.docutils.SphinxDirective
    :parts: -1
 
+.. py:class:: sphinx.ext.inheritance_diagram.InheritanceDiagram
+   :nocontentsentry:
+   :noindexentry:
+
+   The internal class that implements the ``inheritance-diagram`` directive.
 
 
 Configuration

doc/usage/extensions/napoleon.rst

@@ -398,7 +398,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 
    .. seealso::
 
-      :attr:`napoleon_use_admonition_for_examples`
+      :confval:`napoleon_use_admonition_for_examples`
 
 .. confval:: napoleon_use_admonition_for_references
 
@@ -408,7 +408,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 
    .. seealso::
 
-      :attr:`napoleon_use_admonition_for_examples`
+      :confval:`napoleon_use_admonition_for_examples`
 
 .. confval:: napoleon_use_ivar
 
@@ -471,14 +471,14 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
    keywords.
    *Defaults to True.*
 
-   This behaves similarly to  :attr:`napoleon_use_param`. Note unlike docutils,
+   This behaves similarly to :confval:`napoleon_use_param`. Note unlike docutils,
    ``:keyword:`` and ``:param:`` will not be treated the same way - there will
    be a separate "Keyword Arguments" section, rendered in the same fashion as
    "Parameters" section (type links created if possible)
 
    .. seealso::
 
-      :attr:`napoleon_use_param`
+      :confval:`napoleon_use_param`
 
 .. confval:: napoleon_use_rtype
 

doc/usage/restructuredtext/basics.rst

@@ -544,7 +544,7 @@ for details.
 If you want to use some substitutions for all documents, put them into
 :confval:`rst_prolog` or :confval:`rst_epilog` or put them into a separate file
 and include it into all documents you want to use them in, using the
-:rst:dir:`include` directive.  (Be sure to give the include file a file name
+:dudir:`include` directive.  (Be sure to give the include file a file name
 extension differing from that of other source files, to avoid Sphinx finding it
 as a standalone document.)
 
@@ -574,7 +574,7 @@ You can indent text after a comment start to form multiline comments::
 HTML Metadata
 -------------
 
-The :rst:dir:`meta` directive (:dudir:`ref <meta>`) allows specifying the HTML
+The :dudir:`meta` directive allows specifying the HTML
 `metadata element`_ of a Sphinx documentation page.  For example, the
 directive::
 

doc/usage/restructuredtext/directives.rst

@@ -490,6 +490,7 @@ __ https://pygments.org/docs/lexers
       .. versionadded:: 2.1
 
 .. rst:directive:: .. code-block:: [language]
+                   .. sourcecode:: [language]
 
    Example::
 

doc/usage/restructuredtext/domains.rst

@@ -585,7 +585,7 @@ This will render like this:
    :param str recipient: The recipient of the message
    :param str message_body: The body of the message
    :param priority: The priority of the message, can be a number 1-5
-   :type priority: integer or None
+   :type priority: int or None
    :return: the message id
    :rtype: int
    :raises ValueError: if the message_body exceeds 160 characters

sphinx/application.py

@@ -875,7 +875,7 @@ class Sphinx:
                           override: bool = False) -> None:
         """Register a new crossref object type.
 
-        This method is very similar to :meth:`add_object_type` except that the
+        This method is very similar to :meth:`~Sphinx.add_object_type` except that the
         directive it generates must be empty, and will produce no output.
 
         That means that you can add semantic targets to your sources, and refer
@@ -914,9 +914,9 @@ class Sphinx:
     def add_transform(self, transform: type[Transform]) -> None:
         """Register a Docutils transform to be applied after parsing.
 
-        Add the standard docutils :class:`Transform` subclass *transform* to
+        Add the standard docutils :class:`~docutils.transforms.Transform`
-        the list of transforms that are applied after Sphinx parses a reST
+        subclass *transform* to the list of transforms that are applied after
-        document.
+        Sphinx parses a reST document.
 
         :param transform: A transform class
 
@@ -949,9 +949,9 @@ class Sphinx:
     def add_post_transform(self, transform: type[Transform]) -> None:
         """Register a Docutils transform to be applied before writing.
 
-        Add the standard docutils :class:`Transform` subclass *transform* to
+        Add the standard docutils :class:`~docutils.transforms.Transform`
-        the list of transforms that are applied before Sphinx writes a
+        subclass *transform* to the list of transforms that are applied before
-        document.
+        Sphinx writes a document.
 
         :param transform: A transform class
         """
@@ -1132,7 +1132,7 @@ class Sphinx:
         extension.  It must be a subclass of
         :class:`sphinx.ext.autodoc.Documenter`.  This allows auto-documenting
         new types of objects.  See the source of the autodoc module for
-        examples on how to subclass :class:`Documenter`.
+        examples on how to subclass :class:`~sphinx.ext.autodoc.Documenter`.
 
         If *override* is True, the given *cls* is forcedly installed even if
         a documenter having the same name is already installed.

sphinx/builders/__init__.py

@@ -61,7 +61,7 @@ class Builder:
     epilog = ''
 
     #: default translator class for the builder.  This can be overridden by
-    #: :py:meth:`app.set_translator()`.
+    #: :py:meth:`~sphinx.application.Sphinx.set_translator`.
     default_translator_class: type[nodes.NodeVisitor] = None
     # doctree versioning method
     versioning_method = 'none'
@@ -317,7 +317,8 @@ class Builder:
     ) -> None:
         """Main build method.
 
-        First updates the environment, and then calls :meth:`write`.
+        First updates the environment, and then calls
+        :meth:`!write`.
         """
         if summary:
             logger.info(bold(__('building [%s]: ') % self.name) + summary)

sphinx/config.py

@@ -69,15 +69,15 @@ class ENUM:
 
 
 class Config:
-    """Configuration file abstraction.
+    r"""Configuration file abstraction.
 
     The config object makes the values of all config values available as
     attributes.
 
-    It is exposed via the :py:attr:`sphinx.application.Application.config` and
+    It is exposed via the :py:class:`~sphinx.application.Sphinx`\ ``.config``
-    :py:attr:`sphinx.environment.Environment.config` attributes. For example,
+    and :py:class:`sphinx.environment.BuildEnvironment`\ ``.config`` attributes.
-    to get the value of :confval:`language`, use either ``app.config.language``
+    For example, to get the value of :confval:`language`, use either
-    or ``env.config.language``.
+    ``app.config.language`` or ``env.config.language``.
     """
 
     # the values are: (default, what needs to be rebuilt if changed)
@@ -132,8 +132,8 @@ class Config:
         'needs_extensions': ({}, None, []),
         'manpages_url': (None, 'env', []),
         'nitpicky': (False, None, []),
-        'nitpick_ignore': ([], None, []),
+        'nitpick_ignore': (set(), None, [set, list, tuple]),
-        'nitpick_ignore_regex': ([], None, []),
+        'nitpick_ignore_regex': (set(), None, [set, list, tuple]),
         'numfig': (False, 'env', []),
         'numfig_secnum_depth': (1, 'env', []),
         'numfig_format': ({}, 'env', []),  # will be initialized in init_numfig_format()

sphinx/directives/__init__.py

@@ -25,8 +25,6 @@ if TYPE_CHECKING:
 nl_escape_re = re.compile(r'\\\n')
 strip_backslash_re = re.compile(r'\\(.)')
 
-T = TypeVar('T')
-
 
 def optional_int(argument: str) -> int | None:
     """
@@ -41,7 +39,10 @@ def optional_int(argument: str) -> int | None:
         return value
 
 
-class ObjectDescription(SphinxDirective, Generic[T]):
+ObjDescT = TypeVar('ObjDescT')
+
+
+class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
     """
     Directive to describe a class, function or similar object.  Not used
     directly, but subclassed (in domain-specific directives) to add custom
@@ -93,7 +94,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         else:
             return [line.strip() for line in lines]
 
-    def handle_signature(self, sig: str, signode: desc_signature) -> T:
+    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
         """
         Parse the signature *sig* into individual nodes and append them to
         *signode*. If ValueError is raised, parsing is aborted and the whole
@@ -105,7 +106,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: T, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -168,7 +169,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
         within parents in the table of contents.
 
         An example implementations of this method is within the python domain
-        (:meth:`PyObject._toc_entry_name`). The python domain sets the
+        (:meth:`!PyObject._toc_entry_name`). The python domain sets the
         ``_toc_parts`` attribute within the :py:meth:`handle_signature()`
         method.
         """
@@ -221,7 +222,7 @@ class ObjectDescription(SphinxDirective, Generic[T]):
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
 
-        self.names: list[T] = []
+        self.names: list[ObjDescT] = []
         signatures = self.get_signatures()
         for sig in signatures:
             # add a signature node for each signature in the current unit

sphinx/ext/napoleon/__init__.py

@@ -137,7 +137,7 @@ class Config:
 
         See Also
         --------
-        :attr:`napoleon_use_admonition_for_examples`
+        :confval:`napoleon_use_admonition_for_examples`
 
     napoleon_use_admonition_for_references : :obj:`bool` (Defaults to False)
         True to use the ``.. admonition::`` directive for **References**
@@ -145,7 +145,7 @@ class Config:
 
         See Also
         --------
-        :attr:`napoleon_use_admonition_for_examples`
+        :confval:`napoleon_use_admonition_for_examples`
 
     napoleon_use_ivar : :obj:`bool` (Defaults to False)
         True to use the ``:ivar:`` role for instance variables. False to use
@@ -203,7 +203,7 @@ class Config:
         False to use a single ``:keyword arguments:`` role for all the
         keywords.
 
-        This behaves similarly to  :attr:`napoleon_use_param`. Note unlike
+        This behaves similarly to :confval:`napoleon_use_param`. Note unlike
         docutils, ``:keyword:`` and ``:param:`` will not be treated the same
         way - there will be a separate "Keyword Arguments" section, rendered
         in the same fashion as "Parameters" section (type links created if
@@ -211,7 +211,7 @@ class Config:
 
         See Also
         --------
-        :attr:`napoleon_use_param`
+        :confval:`napoleon_use_param`
 
     napoleon_use_rtype : :obj:`bool` (Defaults to True)
         True to use the ``:rtype:`` role for the return type. False to output

sphinx/transforms/post_transforms/code.py

@@ -26,7 +26,7 @@ class HighlightLanguageTransform(SphinxTransform):
     Apply highlight_language to all literal_block nodes.
 
     This refers both :confval:`highlight_language` setting and
-    :rst:dir:`highlightlang` directive.  After processing, this transform
+    :rst:dir:`highlight` directive.  After processing, this transform
     removes ``highlightlang`` node from doctree.
     """
     default_priority = 400

tests/test_config.py

@@ -328,12 +328,12 @@ def test_nitpick_base(app, status, warning):
 
 
 @pytest.mark.sphinx(testroot='nitpicky-warnings', confoverrides={
-    'nitpick_ignore': [
+    'nitpick_ignore': {
         ('py:const', 'prefix.anything.postfix'),
         ('py:class', 'prefix.anything'),
         ('py:class', 'anything.postfix'),
         ('js:class', 'prefix.anything.postfix'),
-    ],
+    },
 })
 def test_nitpick_ignore(app, status, warning):
     app.builder.build_all()