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

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

22 files changed, 122 insertions, 54 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 60d7a3944..19b8b2a2e 100644
--- a/doc/conf.py
+++ b/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 -------------------------------------------------------
 
diff --git a/doc/development/overview.rst b/doc/development/overview.rst
index ad474999a..ea05ec7b9 100644
--- a/doc/development/overview.rst
+++ b/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.
 
diff --git a/doc/development/templating.rst b/doc/development/templating.rst
index c33007604..512240f49 100644
--- a/doc/development/templating.rst
+++ b/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
-  pickle files with the page contents, and postprocess them using a custom tool,
-  or use them in your Web application.
+* You can use the :class:`~sphinxcontrib.serializinghtml.PickleHTMLBuilder` that
+  produces pickle files with the page contents, and postprocess them using a
+  custom tool, or use them in your Web application.
 
 
 Jinja/Sphinx Templating Primer
diff --git a/doc/development/theming.rst b/doc/development/theming.rst
index abe03d59a..3a156fa4f 100644
--- a/doc/development/theming.rst
+++ b/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
diff --git a/doc/development/tutorials/autodoc_ext.rst b/doc/development/tutorials/autodoc_ext.rst
index 8de2e4d4a..cfd23e7e6 100644
--- a/doc/development/tutorials/autodoc_ext.rst
+++ b/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
-because our new extension depends on autodoc. :meth:`~Sphinx.add_autodocumenter`
-is the method that registers our new auto documenter class.
+The :meth:`~sphinx.application.Sphinx.setup_extension` method will pull the
+autodoc extension because our new extension depends on autodoc.
+: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:
 
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst
index c0a5c0d87..f23d8adaf 100644
--- a/doc/development/tutorials/todo.rst
+++ b/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.
 
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index fc92a775c..7f8bf47d3 100644
--- a/doc/extdev/appapi.rst
+++ b/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*
-   as a child.
+   *node*.  Usually this node is a :class:`~nodes.reference` node containing
+   *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
-   a warning about this cross-reference being unresolved.
+   or raise :class:`~sphinx.errors.NoUri` to prevent other handlers in
+   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
-      ``reftype``, ``reftarget``, ``modname`` and ``classname`` attributes
+   :param node: The :class:`~sphinx.addnodes.pending_xref` node to be resolved.
+      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
-   completed, that is, the environment and all doctrees are now up-to-date.
+   Emitted after reading all documents, when the environment and all
+   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
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 61cfbe317..05fa56d65 100644
--- a/doc/extdev/deprecated.rst
+++ b/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
diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst
index 332e5b1f9..072760c3f 100644
--- a/doc/extdev/markupapi.rst
+++ b/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
 
diff --git a/doc/glossary.rst b/doc/glossary.rst
index ca12067c4..e58ce6b47 100644
--- a/doc/glossary.rst
+++ b/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
-      block; and most objects can be cross-referenced to.
+      directive" (e.g. :rst:dir:`py:function` or :rst:dir:`object`) creates such
+      a block; and most objects can be cross-referenced to.
 
    RemoveInSphinxXXXWarning
       The feature which is warned will be removed in Sphinx-XXX version.
diff --git a/doc/latex.rst b/doc/latex.rst
index 5da029a0f..1a9f6a2ec 100644
--- a/doc/latex.rst
+++ b/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.
 
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
index cbf38022b..efc8230dc 100644
--- a/doc/man/sphinx-apidoc.rst
+++ b/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
-style of other automatic API documentation tools.
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document a whole
+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
diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst
index cad22bf22..caeb44b12 100644
--- a/doc/man/sphinx-autogen.rst
+++ b/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
-:rst:dir:`autosummary` listing(s).
+that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included
+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
-other information.
+and each of those files will contain a :py:mod:`~sphinx.ext.autodoc` directive
+and some other information.
 
 See also
 --------
diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst
index 01ec76e40..d050a29c6 100644
--- a/doc/man/sphinx-quickstart.rst
+++ b/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
 
diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst
index 672d65867..6fe68dcdd 100644
--- a/doc/usage/advanced/setuptools.rst
+++ b/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
 ----------------------------
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
index 5fa5b00f1..1cdd23fcc 100644
--- a/doc/usage/advanced/websupport/quickstart.rst
+++ b/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`.
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index c92e468f1..11cd2be31 100644
--- a/doc/usage/configuration.rst
+++ b/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
-      not specified or None is specified,
+      which should be derived from :class:`!sphinx.search.ja.BaseSplitter`.  If
+      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
 
diff --git a/doc/usage/extensions/inheritance.rst b/doc/usage/extensions/inheritance.rst
index 78895915b..5cf1a2ed4 100644
--- a/doc/usage/extensions/inheritance.rst
+++ b/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
diff --git a/doc/usage/extensions/napoleon.rst b/doc/usage/extensions/napoleon.rst
index 2c178d853..d2391da2e 100644
--- a/doc/usage/extensions/napoleon.rst
+++ b/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
 
diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst
index 222a6e4d7..cc3c61524 100644
--- a/doc/usage/restructuredtext/basics.rst
+++ b/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::
 
diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst
index 44e4b5ffe..c9152d1b1 100644
--- a/doc/usage/restructuredtext/directives.rst
+++ b/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::
 
diff --git a/doc/usage/restructuredtext/domains.rst b/doc/usage/restructuredtext/domains.rst
index 96e2bcc69..ac99a28bd 100644
--- a/doc/usage/restructuredtext/domains.rst
+++ b/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