[PATCH] docs: generate manpage from README and HOWTO

[PATCH] docs: generate manpage from README and HOWTO

[Vincent Fu]

We have a longstanding problem where fio documentation updates must be
made to both the HOWTO and manpage.

Here is a solution that generates a manpage from the README and HOWTO
using Sphinx.

The downside to being able to maintain only one version of the
documentation is that this will cause a bit of trouble for those who
package fio and users building fio without Sphinx support will no longer
have a manpage.

Does this seem like a reasonable tradeoff? If so, I will follow up with
patches to remove the original manpage and update the Sphinx-generated
manpage to have the standard NAME, SYNOPSIS, DESCRIPTION, etc layout.

----
Sphinx can generate a manpage from our README.rst and HOWTO.rst. Use
this facility so that we don't have to maintain both the HOWTO and
a seprate, mostly identical manpage.

Use the Sphinx-built manpage for make install. For environments where
Sphinx is unavailable there will be no manpage.

Signed-off-by: Vincent Fu <vincent.fu@samsung.com>
---
 Makefile  | 14 +++++++++++---
 configure | 11 +++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index 0ab4f82c..9799fe46 100644
--- a/Makefile
+++ b/Makefile
@@ -650,8 +650,14 @@ cscope:
 tools/plot/fio2gnuplot.1:
 	@cat tools/plot/fio2gnuplot.manpage | txt2man -t fio2gnuplot >  tools/plot/fio2gnuplot.1
 
+FIO_MANPAGE = $(SRCDIR)/doc/output/man/fio.1
+manpage: HOWTO.rst README.rst
+ifdef CONFIG_SPHINX
+	$(MAKE) -C doc man
+endif
+
 doc: tools/plot/fio2gnuplot.1
-	@man -t ./fio.1 | ps2pdf - fio.pdf
+	@man -t $(FIO_MANPAGE) | ps2pdf - fio.pdf
 	@man -t tools/fio_generate_plots.1 | ps2pdf - fio_generate_plots.pdf
 	@man -t tools/plot/fio2gnuplot.1 | ps2pdf - fio2gnuplot.pdf
 	@man -t tools/hist/fiologparser_hist.py.1 | ps2pdf - fiologparser_hist.pdf
@@ -675,7 +681,7 @@ fulltest:
 		sudo t/zbd/run-tests-against-nullb -s 4;	 	\
 	fi
 
-install: $(PROGS) $(SCRIPTS) $(ENGS_OBJS) tools/plot/fio2gnuplot.1 FORCE
+install: $(PROGS) $(SCRIPTS) $(ENGS_OBJS) tools/plot/fio2gnuplot.1 manpage FORCE
 	$(INSTALL) -m 755 -d $(DESTDIR)$(bindir)
 	$(INSTALL) $(PROGS) $(SCRIPTS) $(DESTDIR)$(bindir)
 ifdef CONFIG_DYNAMIC_ENGINES
@@ -683,7 +689,9 @@ ifdef CONFIG_DYNAMIC_ENGINES
 	$(INSTALL) -m 755 $(SRCDIR)/engines/*.so $(DESTDIR)$(libdir)
 endif
 	$(INSTALL) -m 755 -d $(DESTDIR)$(mandir)/man1
-	$(INSTALL) -m 644 $(SRCDIR)/fio.1 $(DESTDIR)$(mandir)/man1
+ifdef CONFIG_SPHINX
+	$(INSTALL) -m 644 $(FIO_MANPAGE) $(DESTDIR)$(mandir)/man1
+endif
 	$(INSTALL) -m 644 $(SRCDIR)/tools/fio_generate_plots.1 $(DESTDIR)$(mandir)/man1
 	$(INSTALL) -m 644 $(SRCDIR)/tools/plot/fio2gnuplot.1 $(DESTDIR)$(mandir)/man1
 	$(INSTALL) -m 644 $(SRCDIR)/tools/hist/fiologparser_hist.py.1 $(DESTDIR)$(mandir)/man1
diff --git a/configure b/configure
index be4605f9..6849bd9e 100755
--- a/configure
+++ b/configure
@@ -2847,6 +2847,14 @@ EOF
 fi
 print_config "timerfd_create" "$timerfd_create"
 
+##########################################
+# check for sphinx support
+sphinx="no"
+if has "sphinx-build" ; then
+  sphinx="yes"
+fi
+print_config "sphinx" "$sphinx"
+
 #############################################################################
 
 if test "$wordsize" = "64" ; then
@@ -3196,6 +3204,9 @@ fi
 if test "$fcntl_sync" = "yes" ; then
   output_sym "CONFIG_FCNTL_SYNC"
 fi
+if test "$sphinx" = "yes"; then
+  output_sym "CONFIG_SPHINX"
+fi
 
 print_config "Lib-based ioengines dynamic" "$dynamic_engines"
 cat > $TMPC << EOF
-- 
2.25.1

RE: [PATCH] docs: generate manpage from README and HOWTO

[Vincent Fu]

> -----Original Message-----
> From: Vincent Fu
> Sent: Wednesday, March 2, 2022 10:22 AM
> To: fio@vger.kernel.org; axboe@kernel.dk; martin.steigerwald@proact.de;
> sandeen@redhat.com
> Cc: Vincent Fu <vincent.fu@samsung.com>
> Subject: [PATCH] docs: generate manpage from README and HOWTO
> 
> We have a longstanding problem where fio documentation updates must be
> made to both the HOWTO and manpage.
> 
> Here is a solution that generates a manpage from the README and HOWTO
> using Sphinx.
> 
> The downside to being able to maintain only one version of the
> documentation is that this will cause a bit of trouble for those who package
> fio and users building fio without Sphinx support will no longer have a
> manpage.
> 
> Does this seem like a reasonable tradeoff? If so, I will follow up with patches
> to remove the original manpage and update the Sphinx-generated manpage
> to have the standard NAME, SYNOPSIS, DESCRIPTION, etc layout.
> 

Oops, this was intended to be a RFC.

Re: [PATCH] docs: generate manpage from README and HOWTO

[Nick Neumann]

On Wed, Mar 2, 2022 at 9:28 AM Vincent Fu <vincent.fu@samsung.com> wrote:
>
> > -----Original Message-----
> > From: Vincent Fu
> > Sent: Wednesday, March 2, 2022 10:22 AM
> > To: fio@vger.kernel.org; axboe@kernel.dk; martin.steigerwald@proact.de;
> > sandeen@redhat.com
> > Cc: Vincent Fu <vincent.fu@samsung.com>
> > Subject: [PATCH] docs: generate manpage from README and HOWTO
> >
> > We have a longstanding problem where fio documentation updates must be
> > made to both the HOWTO and manpage.
> >
> > Here is a solution that generates a manpage from the README and HOWTO
> > using Sphinx.
> >
> > The downside to being able to maintain only one version of the
> > documentation is that this will cause a bit of trouble for those who package
> > fio and users building fio without Sphinx support will no longer have a
> > manpage.
> >
> > Does this seem like a reasonable tradeoff? If so, I will follow up with patches
> > to remove the original manpage and update the Sphinx-generated manpage
> > to have the standard NAME, SYNOPSIS, DESCRIPTION, etc layout.
> >
>
> Oops, this was intended to be a RFC.

I'm fairly green in linux so I'm not sure about the Sphinx
implications, but single-sourcing the HOWTO/manpage would be really
nice. Also, the documentation for command-line options is actually
currently triple-sourced (HOWTO.rst, fio.1, and options.c). It would
also be nice (not asking for now, just wishing for someday) if all of
the options documentation could be single-sourced, likely from
options.c.

Re: [PATCH] docs: generate manpage from README and HOWTO

[Jens Axboe]

On 3/2/22 8:22 AM, Vincent Fu wrote:
> We have a longstanding problem where fio documentation updates must be
> made to both the HOWTO and manpage.
> 
> Here is a solution that generates a manpage from the README and HOWTO
> using Sphinx.
> 
> The downside to being able to maintain only one version of the
> documentation is that this will cause a bit of trouble for those who
> package fio and users building fio without Sphinx support will no longer
> have a manpage.

That should most certainly be solvable.

> Does this seem like a reasonable tradeoff? If so, I will follow up with
> patches to remove the original manpage and update the Sphinx-generated
> manpage to have the standard NAME, SYNOPSIS, DESCRIPTION, etc layout.

Definitely! I absolutely hate that we have duplicated documentation,
and having to ask people to update both when they submit changes is
definitely not idea.

I don't have a lot of time to look into this right now, but would
certainly entertain applying the patch if I know the submitter has done
the legwork on checking if things look good post the patch.

-- 
Jens Axboe