mbox series

[v2,0/3] docs: fix and cleanup footnotes

Message ID 20241011111249.47530-1-pbonzini@redhat.com (mailing list archive)
Headers show
Series docs: fix and cleanup footnotes | expand

Message

Paolo Bonzini Oct. 11, 2024, 11:12 a.m. UTC
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

v1->v2: improve commit messages
        replace patch 2, absorbing the rapl-msr.rst changes into it


Paolo Bonzini (3):
  docs: fix invalid footnote syntax
  docs: avoid footnotes consisting of just URLs
  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    | 26 +++++++++++++-------------
 docs/specs/fw_cfg.rst               |  4 ++--
 docs/specs/rapl-msr.rst             | 25 ++++++++++++-------------
 8 files changed, 38 insertions(+), 39 deletions(-)

Comments

Peter Maydell Oct. 11, 2024, 12:27 p.m. UTC | #1
On Fri, 11 Oct 2024 at 12:12, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> 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.

In particular we hit this on the macos14 CI job now:

https://gitlab.com/qemu-project/qemu/-/jobs/8054823697

I'll give this a bit more time on-list for review from
others if they want to, but I plan to apply this directly
to fix that CI job on Monday.

-- PMM
Paolo Bonzini Oct. 11, 2024, 3:32 p.m. UTC | #2
On Fri, Oct 11, 2024 at 2:27 PM Peter Maydell <peter.maydell@linaro.org> wrote:
>
> On Fri, 11 Oct 2024 at 12:12, Paolo Bonzini <pbonzini@redhat.com> wrote:
> >
> > 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.
>
> In particular we hit this on the macos14 CI job now:
>
> https://gitlab.com/qemu-project/qemu/-/jobs/8054823697
>
> I'll give this a bit more time on-list for review from
> others if they want to, but I plan to apply this directly
> to fix that CI job on Monday.

Ok, I'll also include it in my pull request anyway.

Paolo