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@xxxxxxxxxxx> --- 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
