doc: use intersphinx explicit external references

See [1]. The role was added in Sphinx 4.4, so require that for the
documentation build.

[1] https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

doc/conf.py

@@ -35,7 +35,9 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+# The documentation uses the intersphinx explicit external reference role. Note
+# that this is not the same as Hawkmoth extension minimum version requirement.
+needs_sphinx = '4.4'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

doc/extension.rst

@@ -4,9 +4,9 @@ C Autodoc Extension
 ===================
 
 Hawkmoth provides a Sphinx extension that adds :ref:`new directives
-<directives>` to the Sphinx :any:`C domain <sphinx:c-domain>` to incorporate
-formatted C source code comments into a document. Hawkmoth is Sphinx
-:any:`sphinx:sphinx.ext.autodoc` for C.
+<directives>` to the Sphinx :external+sphinx:ref:`C domain <c-domain>` to
+incorporate formatted C source code comments into a document. Hawkmoth is Sphinx
+:py:mod:`sphinx.ext.autodoc` for C.
 
 For this to work, the documentation comments must of course be written in
 correct reStructuredText. See :ref:`documentation comment syntax <syntax>` for
@@ -18,8 +18,8 @@ dependencies.
 Usage
 -----
 
-Add ``hawkmoth`` to :confval:`sphinx:extensions` in ``conf.py``. Note that
-depending on the packaging and installation directory, this may require
+Add ``hawkmoth`` to :external+sphinx:confval:`extensions` in ``conf.py``. Note
+that depending on the packaging and installation directory, this may require
 adjusting the :envvar:`python:PYTHONPATH`.
 
 For example:
@@ -37,8 +37,8 @@ The extension has a few configuration options that can be set in ``conf.py``:
    :type: str
 
    Path to the root of the source files. Defaults to the
-   :term:`sphinx:configuration directory`, i.e. the directory containing
-   ``conf.py``.
+   :external+sphinx:term:`configuration directory`, i.e. the directory
+   containing ``conf.py``.
 
    To use paths relative to the configuration directory, use
    :func:`python:os.path.abspath`, for example:

doc/index.rst

@@ -1,11 +1,11 @@
 Hawkmoth - Sphinx Autodoc for C
 ===============================
 
-Hawkmoth is a minimalistic Sphinx_ :any:`C Domain <sphinx:c-domain>` autodoc
-directive extension to incorporate formatted C source code comments written in
-reStructuredText_ into Sphinx based documentation. It uses Clang_ Python
-Bindings for parsing, and generates C Domain directives for C API documentation,
-and more. In short, Hawkmoth is Sphinx Autodoc for C.
+Hawkmoth is a minimalistic Sphinx_ :external+sphinx:ref:`C Domain <c-domain>`
+autodoc directive extension to incorporate formatted C source code comments
+written in reStructuredText_ into Sphinx based documentation. It uses Clang_
+Python Bindings for parsing, and generates C Domain directives for C API
+documentation, and more. In short, Hawkmoth is Sphinx Autodoc for C.
 
 Hawkmoth aims to be a compelling alternative for documenting C projects using
 Sphinx, mainly through its simplicity of design, implementation and use.

doc/syntax.rst

@@ -94,7 +94,7 @@ enable the support.
 Cross-Referencing C Constructs
 ------------------------------
 
-Use :any:`sphinx:c-domain` roles for cross-referencing as follows:
+Use :external+sphinx:ref:`c-domain` roles for cross-referencing as follows:
 
 - ``:c:data:`name``` for variables.
 
@@ -106,6 +106,6 @@ Use :any:`sphinx:c-domain` roles for cross-referencing as follows:
 
 - ``:c:member:`name.membername``` for struct and union members.
 
-See the Sphinx :any:`sphinx:basic-domain-markup` and generic
-:any:`sphinx:xref-syntax` for further details on cross-referencing, and how to
-specify the default domain for brevity.
+See the Sphinx :external+sphinx:ref:`basic-domain-markup` and generic
+:external+sphinx:ref:`xref-syntax` for further details on cross-referencing, and
+how to specify the default domain for brevity.