From 17e74c9cfef895a4afe5c4ed5468ffd59e9442e0 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Sat, 21 Jan 2023 22:31:34 +0200 Subject: [PATCH] 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 | 4 +++- doc/extension.rst | 14 +++++++------- doc/index.rst | 10 +++++----- doc/syntax.rst | 8 ++++---- 4 files changed, 19 insertions(+), 17 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 2805316e..1cbe9619 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/extension.rst b/doc/extension.rst index 146d849f..7b46a43b 100644 --- a/doc/extension.rst +++ b/doc/extension.rst @@ -4,9 +4,9 @@ C Autodoc Extension =================== Hawkmoth provides a Sphinx extension that adds :ref:`new directives -` to the Sphinx :any:`C domain ` to incorporate -formatted C source code comments into a document. Hawkmoth is Sphinx -:any:`sphinx:sphinx.ext.autodoc` for C. +` to the Sphinx :external+sphinx:ref:`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 ` 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: diff --git a/doc/index.rst b/doc/index.rst index 15a9d47a..cc0a9a81 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,11 +1,11 @@ Hawkmoth - Sphinx Autodoc for C =============================== -Hawkmoth is a minimalistic Sphinx_ :any:`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 ` +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. diff --git a/doc/syntax.rst b/doc/syntax.rst index 9fe233d4..7dc0ae02 100644 --- a/doc/syntax.rst +++ b/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.