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 <vincent.fu@samsung.com>

diff --git a/doc/conf.py b/doc/conf.py
index 844f951ab7ecd17eb9bbbf0ae4b323a67cd3a155..18a8dccce329d5cbda0eb0d331275c4f791a9886 100644 (file)
--- 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 34e7fde988536638a8afd74b393d00637802c79a..cad84c7c7ef5bb367b210442674f949cd55317e7 100644 (file)
--- 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 (file)
index dc1d1c0..0000000
--- a/doc/fio_man.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-:orphan:
-
-Fio Manpage
-===========
-
-(rev. |release|)
-
-
-.. include:: ../README.rst
-
-
-.. include:: ../HOWTO.rst