[PATCH 0/3] docs: fix and cleanup footnotes

[PATCH 0/3] docs: fix and cleanup footnotes

[Paolo Bonzini]

Sphinx 8.1.0 got a lot better at detecting unreferenced footnotes, and
we have three of them---which causes the build to fail when the latest
version of sphinx is installed from Pip.

Patches 1 and 2 fix them, while the third is a general improvement in
the appearance of the rendered footnotes and the consistency of the
rST syntax.

An example of a failing job is https://gitlab.com/bonzini/qemu/-/jobs/8060240732.

Paolo

Paolo Bonzini (3):
  docs: fix invalid footnote syntax
  docs: avoid unreferenced footnote
  docs: use consistent markup for footnotes

 docs/devel/atomics.rst              | 6 +++---
 docs/devel/build-system.rst         | 6 +++---
 docs/devel/loads-stores.rst         | 2 +-
 docs/devel/maintainers.rst          | 4 ++--
 docs/devel/migration/mapped-ram.rst | 4 ++--
 docs/devel/testing/acpi-bits.rst    | 4 ++--
 docs/specs/fw_cfg.rst               | 4 ++--
 docs/specs/rapl-msr.rst             | 4 ++--
 8 files changed, 17 insertions(+), 17 deletions(-)

-- 
2.46.2

[PATCH 1/3] docs: fix invalid footnote syntax

[Paolo Bonzini]

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 <pbonzini@redhat.com>
---
 docs/devel/atomics.rst      | 2 +-
 docs/devel/build-system.rst | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

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
-- 
2.46.2

Re: [PATCH 1/3] docs: fix invalid footnote syntax

[Peter Maydell]

On Fri, 11 Oct 2024 at 10:50, Paolo Bonzini <pbonzini@redhat.com> 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 <peter.maydell@linaro.org>

thanks
-- PMM

[PATCH 2/3] docs: avoid unreferenced footnote

[Paolo Bonzini]

The link to fosdem.org is inlined but also included in the footnote [#c].
Replace the inline link with a reference to the footnote, because Sphinx
8.1.0 is a lot stricter about unreferenced footnotes.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/devel/testing/acpi-bits.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/devel/testing/acpi-bits.rst b/docs/devel/testing/acpi-bits.rst
index 78aeb6aa3c4..2e4f1d23def 100644
--- a/docs/devel/testing/acpi-bits.rst
+++ b/docs/devel/testing/acpi-bits.rst
@@ -37,8 +37,8 @@ dependent submodules `here <https://gitlab.com/qemu-project/biosbits-bits>`__.
 This fork contains numerous fixes, a newer acpica and changes specific to
 running these functional QEMU tests using bits. The author of this document
 is the sole maintainer of the QEMU fork of bios bits repository. For more
-information, please see author's `FOSDEM talk on this bios-bits based test
-framework <https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/>`__.
+information, please see author's FOSDEM talk on this bios-bits based test
+framework\ [#c]_.
 
 *********************************
 Description of the test framework
-- 
2.46.2

Re: [PATCH 2/3] docs: avoid unreferenced footnote

[Peter Maydell]

On Fri, 11 Oct 2024 at 10:50, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> The link to fosdem.org is inlined but also included in the footnote [#c].
> Replace the inline link with a reference to the footnote, because Sphinx
> 8.1.0 is a lot stricter about unreferenced footnotes.
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  docs/devel/testing/acpi-bits.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/testing/acpi-bits.rst b/docs/devel/testing/acpi-bits.rst
> index 78aeb6aa3c4..2e4f1d23def 100644
> --- a/docs/devel/testing/acpi-bits.rst
> +++ b/docs/devel/testing/acpi-bits.rst
> @@ -37,8 +37,8 @@ dependent submodules `here <https://gitlab.com/qemu-project/biosbits-bits>`__.
>  This fork contains numerous fixes, a newer acpica and changes specific to
>  running these functional QEMU tests using bits. The author of this document
>  is the sole maintainer of the QEMU fork of bios bits repository. For more
> -information, please see author's `FOSDEM talk on this bios-bits based test
> -framework <https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/>`__.
> +information, please see author's FOSDEM talk on this bios-bits based test
> +framework\ [#c]_.
>
>  *********************************
>  Description of the test framework

I think for this doc, because all the footnotes are
simply URLs it will produce a better HTML document if
we instead convert them all to hyperlinks in line.
At the moment you have to click on the footnote link
and then again on the URL.

thanks
-- PMM

[PATCH 3/3] docs: use consistent markup for footnotes

[Paolo Bonzini]

Always use a named reference for clarity, and ensure the space is escaped if the
footnote must attach to the preceding word.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/devel/atomics.rst              | 6 +++---
 docs/devel/build-system.rst         | 2 +-
 docs/devel/loads-stores.rst         | 2 +-
 docs/devel/maintainers.rst          | 4 ++--
 docs/devel/migration/mapped-ram.rst | 4 ++--
 docs/specs/fw_cfg.rst               | 4 ++--
 docs/specs/rapl-msr.rst             | 4 ++--
 7 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/docs/devel/atomics.rst b/docs/devel/atomics.rst
index 6bf032f9005..95c7b77c01e 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\ [#alpha]_.
 
   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
@@ -212,7 +212,7 @@ They come in six kinds:
   than actually loading the address itself, then it's a _control_
   dependency and a full read barrier or better is required.
 
-.. [#] The DEC Alpha is an exception, because ``smp_read_barrier_depends()``
+.. [#alpha] The DEC Alpha is an exception, because ``smp_read_barrier_depends()``
    needs a processor barrier.  On strongly-ordered architectures such
    as x86 or s390, ``smp_rmb()`` and ``qatomic_load_acquire()`` can
    also be compiler barriers only.
@@ -295,7 +295,7 @@ Acquire/release pairing and the *synchronizes-with* relation
 ------------------------------------------------------------
 
 Atomic operations other than ``qatomic_set()`` and ``qatomic_read()`` have
-either *acquire* or *release* semantics [#rmw]_.  This has two effects:
+either *acquire* or *release* semantics\ [#rmw]_.  This has two effects:
 
 .. [#rmw] Read-modify-write operations can have both---acquire applies to the
           read part, and release to the write.
diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
index fa1c59d9fd8..d42045a2325 100644
--- a/docs/devel/build-system.rst
+++ b/docs/devel/build-system.rst
@@ -333,7 +333,7 @@ into each emulator:
 
 ``default-configs/targets/*.mak``
   These files mostly define symbols that appear in the ``*-config-target.h``
-  file for each emulator [#cfgtarget]_.  However, the ``TARGET_ARCH``
+  file for each emulator\ [#cfgtarget]_.  However, the ``TARGET_ARCH``
   and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and
   ``target/`` subdirectories that are compiled into each target.
 
diff --git a/docs/devel/loads-stores.rst b/docs/devel/loads-stores.rst
index ec627aa9c06..9471bac8599 100644
--- a/docs/devel/loads-stores.rst
+++ b/docs/devel/loads-stores.rst
@@ -95,7 +95,7 @@ guest CPU state in case of a guest CPU exception.  This is passed
 to ``cpu_restore_state()``.  Therefore the value should either be 0,
 to indicate that the guest CPU state is already synchronized, or
 the result of ``GETPC()`` from the top level ``HELPER(foo)``
-function, which is a return address into the generated code [#gpc]_.
+function, which is a return address into the generated code\ [#gpc]_.
 
 .. [#gpc] Note that ``GETPC()`` should be used with great care: calling
           it in other functions that are *not* the top level
diff --git a/docs/devel/maintainers.rst b/docs/devel/maintainers.rst
index 5c907d901cd..88a613ed74f 100644
--- a/docs/devel/maintainers.rst
+++ b/docs/devel/maintainers.rst
@@ -99,9 +99,9 @@ members of the QEMU community, you should make arrangements to attend
 a `KeySigningParty <https://wiki.qemu.org/KeySigningParty>`__ (for
 example at KVM Forum) or make alternative arrangements to have your
 key signed by an attendee. Key signing requires meeting another
-community member **in person** [#]_ so please make appropriate
+community member **in person**\ [#2020]_ so please make appropriate
 arrangements.
 
-.. [#] In recent pandemic times we have had to exercise some
+.. [#2020] In recent pandemic times we have had to exercise some
        flexibility here. Maintainers still need to sign their pull
        requests though.
diff --git a/docs/devel/migration/mapped-ram.rst b/docs/devel/migration/mapped-ram.rst
index d352b546e96..b08c2b433c4 100644
--- a/docs/devel/migration/mapped-ram.rst
+++ b/docs/devel/migration/mapped-ram.rst
@@ -44,7 +44,7 @@ Use-cases
 
 The mapped-ram feature was designed for use cases where the migration
 stream will be directed to a file in the filesystem and not
-immediately restored on the destination VM [#]_. These could be
+immediately restored on the destination VM\ [#alternatives]_. These could be
 thought of as snapshots. We can further categorize them into live and
 non-live.
 
@@ -70,7 +70,7 @@ mapped-ram in this scenario is portability since background-snapshot
 depends on async dirty tracking (KVM_GET_DIRTY_LOG) which is not
 supported outside of Linux.
 
-.. [#] While this same effect could be obtained with the usage of
+.. [#alternatives] While this same effect could be obtained with the usage of
        snapshots or the ``file:`` migration alone, mapped-ram provides
        a performance increase for VMs with larger RAM sizes (10s to
        100s of GiBs), specially if the VM has been stopped beforehand.
diff --git a/docs/specs/fw_cfg.rst b/docs/specs/fw_cfg.rst
index 5ad47a901c9..c353957e1d3 100644
--- a/docs/specs/fw_cfg.rst
+++ b/docs/specs/fw_cfg.rst
@@ -54,11 +54,11 @@ Data Register
 -------------
 
 * Read/Write (writes ignored as of QEMU v2.4, but see the DMA interface)
-* Location: platform dependent (IOport [#]_ or MMIO)
+* Location: platform dependent (IOport [#placement]_ or MMIO)
 * Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO)
 * Endianness: string-preserving
 
-.. [#]
+.. [#placement]
     On platforms where the data register is exposed as an IOport, its
     port number will always be one greater than the port number of the
     selector register. In other words, the two ports overlap, and can not
diff --git a/docs/specs/rapl-msr.rst b/docs/specs/rapl-msr.rst
index 1202ee89bee..901ce83bfa8 100644
--- a/docs/specs/rapl-msr.rst
+++ b/docs/specs/rapl-msr.rst
@@ -9,7 +9,7 @@ The consumption is reported via MSRs (model specific registers) like
 MSR_PKG_ENERGY_STATUS for the CPU package power domain. These MSRs are 64 bits
 registers that represent the accumulated energy consumption in micro Joules.
 
-Thanks to the MSR Filtering patch [#a]_ not all MSRs are handled by KVM. Some
+Thanks to the MSR Filtering patch\ [#a]_ not all MSRs are handled by KVM. Some
 of them can now be handled by the userspace (QEMU). It uses a mechanism called
 "MSR filtering" where a list of MSRs is given at init time of a VM to KVM so
 that a callback is put in place. The design of this patch uses only this
@@ -92,7 +92,7 @@ found by the sysconf system call. A typical value of clock ticks per second is
 package has 4 cores, 400 ticks maximum can be scheduled on all the cores
 of the package for a period of 1 second.
 
-The /proc/[pid]/stat [#b]_ is a sysfs file that can give the executed time of a
+The /proc/[pid]/stat\ [#b]_ is a sysfs file that can give the executed time of a
 process with the [pid] as the process ID. It gives the amount of ticks the
 process has been scheduled in userspace (utime) and kernel space (stime).
 
-- 
2.46.2

Re: [PATCH 3/3] docs: use consistent markup for footnotes

[Peter Maydell]

On Fri, 11 Oct 2024 at 10:50, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> Always use a named reference for clarity, and ensure the space is escaped if the
> footnote must attach to the preceding word.
>
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>  docs/devel/atomics.rst              | 6 +++---
>  docs/devel/build-system.rst         | 2 +-
>  docs/devel/loads-stores.rst         | 2 +-
>  docs/devel/maintainers.rst          | 4 ++--
>  docs/devel/migration/mapped-ram.rst | 4 ++--
>  docs/specs/fw_cfg.rst               | 4 ++--
>  docs/specs/rapl-msr.rst             | 4 ++--
>  7 files changed, 13 insertions(+), 13 deletions(-)
>

> diff --git a/docs/specs/fw_cfg.rst b/docs/specs/fw_cfg.rst
> index 5ad47a901c9..c353957e1d3 100644
> --- a/docs/specs/fw_cfg.rst
> +++ b/docs/specs/fw_cfg.rst
> @@ -54,11 +54,11 @@ Data Register
>  -------------
>
>  * Read/Write (writes ignored as of QEMU v2.4, but see the DMA interface)
> -* Location: platform dependent (IOport [#]_ or MMIO)
> +* Location: platform dependent (IOport [#placement]_ or MMIO)

Missing "\" ?

>  * Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO)
>  * Endianness: string-preserving
>
> -.. [#]
> +.. [#placement]
>      On platforms where the data register is exposed as an IOport, its
>      port number will always be one greater than the port number of the
>      selector register. In other words, the two ports overlap, and can not
> diff --git a/docs/specs/rapl-msr.rst b/docs/specs/rapl-msr.rst
> index 1202ee89bee..901ce83bfa8 100644
> --- a/docs/specs/rapl-msr.rst
> +++ b/docs/specs/rapl-msr.rst
> @@ -9,7 +9,7 @@ The consumption is reported via MSRs (model specific registers) like
>  MSR_PKG_ENERGY_STATUS for the CPU package power domain. These MSRs are 64 bits
>  registers that represent the accumulated energy consumption in micro Joules.
>
> -Thanks to the MSR Filtering patch [#a]_ not all MSRs are handled by KVM. Some
> +Thanks to the MSR Filtering patch\ [#a]_ not all MSRs are handled by KVM. Some
>  of them can now be handled by the userspace (QEMU). It uses a mechanism called
>  "MSR filtering" where a list of MSRs is given at init time of a VM to KVM so
>  that a callback is put in place. The design of this patch uses only this
> @@ -92,7 +92,7 @@ found by the sysconf system call. A typical value of clock ticks per second is
>  package has 4 cores, 400 ticks maximum can be scheduled on all the cores
>  of the package for a period of 1 second.
>
> -The /proc/[pid]/stat [#b]_ is a sysfs file that can give the executed time of a
> +The /proc/[pid]/stat\ [#b]_ is a sysfs file that can give the executed time of a
>  process with the [pid] as the process ID. It gives the amount of ticks the
>  process has been scheduled in userspace (utime) and kernel space (stime).

(This is another file where the footnotes are just URLs and we
should turn them into direct links I think.)

With the missing "\" fixed,
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM