[1/3] docs: fix invalid footnote syntax

Commit Message

Paolo Bonzini Oct. 11, 2024, 9:49 a.m. UTC

All footnotes must come after a separator in reStructuredText.  Fix the
two files in which this does not happen.  This mistake is caught by
Sphinx 8.1.0 as an unreferenced footnote.

Signed-off-by: Paolo Bonzini <[e-mail]>
---
 docs/devel/atomics.rst      | 2 +-
 docs/devel/build-system.rst | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

Comments

Peter Maydell Oct. 11, 2024, 10:43 a.m. UTC | #1

On Fri, 11 Oct 2024 at 10:50, Paolo Bonzini <[e-mail]> wrote:
>
> All footnotes must come after a separator in reStructuredText.  Fix the
> two files in which this does not happen.  This mistake is caught by
> Sphinx 8.1.0 as an unreferenced footnote.

Worth noting in the commit message that this isn't just new
Sphinx being picky about syntax -- the current docs actually
misrender the intended footnote link literally:

...from the venv itself[#distlib]_. If no...

It's a shame that the way the footnote syntax is defined
means that you have to remember this awkward "\ " in the
really common case of "footnote marker at end of word or
sentence, and that the rST documentation's examples of
footnote syntax contain only artificial examples and none
where you need this.

Reviewed-by: Peter Maydell <[e-mail]>

thanks
-- PMM

Patch

diff --git a/docs/devel/atomics.rst b/docs/devel/atomics.rst
index b77c6e13e18..6bf032f9005 100644
--- a/docs/devel/atomics.rst
+++ b/docs/devel/atomics.rst
@@ -204,7 +204,7 @@  They come in six kinds:
   before the second with respect to the other components of the system.
   Therefore, unlike ``smp_rmb()`` or ``qatomic_load_acquire()``,
   ``smp_read_barrier_depends()`` can be just a compiler barrier on
-  weakly-ordered architectures such as Arm or PPC[#]_.
+  weakly-ordered architectures such as Arm or PPC\ [#]_.
 
   Note that the first load really has to have a _data_ dependency and not
   a control dependency.  If the address for the second load is dependent
diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index 79eceb179de..fa1c59d9fd8 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -145,13 +145,13 @@  was installed in the ``site-packages`` directory of another interpreter,
 or with the wrong ``pip`` program.
 
 If a package is available for the chosen interpreter, ``configure``
-prepares a small script that invokes it from the venv itself[#distlib]_.
+prepares a small script that invokes it from the venv itself\ [#distlib]_.
 If not, ``configure`` can also optionally install dependencies in the
 virtual environment with ``pip``, either from wheels in ``python/wheels``
 or by downloading the package with PyPI.  Downloading can be disabled with
 ``--disable-download``; and anyway, it only happens when a ``configure``
 option (currently, only ``--enable-docs``) is explicitly enabled but
-the dependencies are not present[#pip]_.
+the dependencies are not present\ [#pip]_.
 
 .. [#distlib] The scripts are created based on the package's metadata,
               specifically the ``console_script`` entry points.  This is the