From 6112c0f5a86c6b437e7158ab40a6e9384ce95e85 Mon Sep 17 00:00:00 2001 From: Vincent Fu Date: Tue, 27 Sep 2022 07:43:49 -0700 Subject: [PATCH] doc: build manpage from fio_doc.rst instead of fio_man.rst Sphinx prints warnings when it encounters duplicate labels. In HOWTO.rst are labels for int, irange, and bool. We include HOWTO.rst in both fio_doc.rst and fio_man.rst. Since labels must be unique across all files, Sphinx prints warnings for these labels. For an unknown reason, Sphinx previously did not issue warnings for the duplicate labels mentioned above until 5.2.0. But Sphinx 5.2.1 is now installed for the macOS 11 image in GitHub Actions. So now we see Sphinx warnings when building documentation in GitHub Actions. Our CI treats Sphinx warnings as test failures. So our macOS builds are marked as failures. Resolve this problem by eliminating the separate fio_man.rst file and just building the manpage from the largely equivalent fio_doc.rst. Successful build with 5.1.1: https://github.com/axboe/fio/actions/runs/3106980788/jobs/5034529793 Failed build with 5.2.1: https://github.com/axboe/fio/actions/runs/3129974184/jobs/5079696775 Link: https://github.com/sphinx-doc/sphinx/pull/10781 Link: https://github.com/sphinx-doc/sphinx/issues/10870 Signed-off-by: Vincent Fu --- doc/conf.py | 2 +- doc/fio_doc.rst | 42 +++++++++++++++++++++--------------------- doc/fio_man.rst | 12 ------------ 3 files changed, 22 insertions(+), 34 deletions(-) delete mode 100644 doc/fio_man.rst diff --git a/doc/conf.py b/doc/conf.py index 844f951a..18a8dccc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -318,7 +318,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('fio_man', 'fio', 'flexible I/O tester', + ('fio_doc', 'fio', 'flexible I/O tester', [author], 1) ] diff --git a/doc/fio_doc.rst b/doc/fio_doc.rst index 34e7fde9..cad84c7c 100644 --- a/doc/fio_doc.rst +++ b/doc/fio_doc.rst @@ -7,45 +7,45 @@ fio - Flexible I/O tester rev. |version| .. include:: ../HOWTO.rst +.. only:: not man + Examples + ======== -Examples -======== + .. include:: fio_examples.rst -.. include:: fio_examples.rst + TODO + ==== -TODO -==== + GFIO TODO + --------- -GFIO TODO ---------- + .. include:: ../GFIO-TODO -.. include:: ../GFIO-TODO + Server TODO + ----------- -Server TODO ------------ + .. include:: ../SERVER-TODO -.. include:: ../SERVER-TODO + Steady State TODO + ----------------- -Steady State TODO ------------------ + .. include:: ../STEADYSTATE-TODO -.. include:: ../STEADYSTATE-TODO + Moral License + ============= -Moral License -============= + .. include:: ../MORAL-LICENSE -.. include:: ../MORAL-LICENSE + License + ======= -License -======= - -.. literalinclude:: ../COPYING + .. literalinclude:: ../COPYING diff --git a/doc/fio_man.rst b/doc/fio_man.rst deleted file mode 100644 index dc1d1c0d..00000000 --- a/doc/fio_man.rst +++ /dev/null @@ -1,12 +0,0 @@ -:orphan: - -Fio Manpage -=========== - -(rev. |release|) - - -.. include:: ../README.rst - - -.. include:: ../HOWTO.rst -- 2.25.1