Re: [Qemu-devel] [PATCH] qemu-ga: Convert invocation documentation to rST

[Michael Roth]

Quoting Peter Maydell (2019-06-13 10:29:33)
> On Thu, 13 Jun 2019 at 16:20, Michael Roth <address@hidden> wrote:
> >
> > Quoting Peter Maydell (2019-06-10 08:45:45)
> > > The qemu-ga documentation is currently in qemu-ga.texi in
> > > Texinfo format, which we present to the user as:
> > >  * a qemu-ga manpage
> > >  * a section of the main qemu-doc HTML documentation
> > >
> > > Convert the documentation to rST format, and present it to
> > > the user as:
> > >  * a qemu-ga manpage
> > >  * part of the interop/ Sphinx manual
> > >
> > > Signed-off-by: Peter Maydell <address@hidden>
> 
> > > +# Canned command to build manpages from a single manual
> > > +build-manpages = $(call quiet-command,CONFDIR="$(qemu_confdir)" 
> > > sphinx-build $(if $(V),,-q) -W -n -b man -D version=$(VERSION) -D 
> > > release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1
> $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
> 
> > > --- a/docs/conf.py
> > > +++ b/docs/conf.py
> > > @@ -115,6 +115,14 @@ todo_include_todos = False
> > >  # with "option::" in the document being processed. Turn that off.
> > >  suppress_warnings = ["ref.option"]
> > >
> > > +# The rst_epilog fragment is effectively included in every rST file.
> > > +# We use it to define substitutions based on build config that
> > > +# can then be used in the documentation. The fallback if the
> > > +# environment variable is not set is for the benefit of readthedocs
> > > +# style document building; our Makefile always sets the variable.
> > > +confdir = os.getenv('CONFDIR', "/usr/local/etc")
> > > +rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
> > > +
> >
> > When testing this I have the following in my qemu build directory (via
> > ./configure --prefix=/home/mdroth/w/qemu-install2):
> >
> >   $ grep -r CONFDIR
> >   config-host.h-timestamp:#define CONFIG_QEMU_CONFDIR 
> > "/home/mdroth/w/qemu-install2/etc/qemu"
> >   qemu-doc.txt:     user-provided config files on SYSCONFDIR.
> >   config-host.h:#define CONFIG_QEMU_CONFDIR 
> > "/home/mdroth/w/qemu-install2/etc/qemu"
> >   docs/version.texi:@set CONFDIR /home/mdroth/w/qemu-install2/etc/qemu
> >
> > but the following input for the qemu-ga man page:
> >
> >   qemu-ga will read a system configuration file on startup (located at
> >   |CONFDIR|\ ``/qemu-ga.conf`` by default),
> >
> > ends up as this in the generated man page:
> >
> >   qemu-ga will read a system configuration file on startup (located at 
> > /usr/local/etc/qemu-ga.conf
> >   by  default),
> >
> > is this expected, or are we unexpectedly falling back to the default
> > value here?
> 
> No, if you're invoking Sphinx via the makefile then we should
> be passing CONFDIR="$(qemu_confdir)" to set the environment
> variable when we invoke it. Can you try doing a build with V=1
> to check the sphinx command line ?

Here's the relevant output from make. The environment variable seems to
be defined as expected but I guess sphinx-build isn't picking it up for
some reason?

( echo "@set VERSION 4.0.50" && echo "@set CONFDIR 
/home/mdroth/w/qemu-install2/etc/qemu" )> docs/version.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < 
/home/mdroth/w/qemu4.git/qemu-options.hx > qemu-options.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < 
/home/mdroth/w/qemu4.git/hmp-commands.hx > qemu-monitor.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < 
/home/mdroth/w/qemu4.git/qemu-img-cmds.hx > qemu-img-cmds.texi
sh /home/mdroth/w/qemu4.git/scripts/hxtool -t < 
/home/mdroth/w/qemu4.git/hmp-commands-info.hx > qemu-monitor-info.texi
LC_ALL=C makeinfo --no-split --number-sections -I docs -I 
/home/mdroth/w/qemu4.git -I . --no-headers --html 
/home/mdroth/w/qemu4.git/qemu-doc.texi -o qemu-doc.html
LC_ALL=C makeinfo --no-split --number-sections -I docs -I 
/home/mdroth/w/qemu4.git -I . --no-headers --plaintext 
/home/mdroth/w/qemu4.git/qemu-doc.texi -o qemu-doc.txt
perl -Ww -- /home/mdroth/w/qemu4.git/scripts/texi2pod.pl -I docs -I 
/home/mdroth/w/qemu4.git -I . -DVERSION="4.0.50" 
-DCONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" 
/home/mdroth/w/qemu4.git/qemu-doc.texi qemu.1.pod && pod2man --utf8 --section=1 
--center=" " --release=" " qemu.1.pod > qemu.1
perl -Ww -- /home/mdroth/w/qemu4.git/scripts/texi2pod.pl -I docs -I 
/home/mdroth/w/qemu4.git -I . -DVERSION="4.0.50" 
-DCONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" 
/home/mdroth/w/qemu4.git/qemu-img.texi qemu-img.1.pod && pod2man --utf8 
--section=1 --center=" " --release=" " qemu-img.1.pod > qemu-img.1
perl -Ww -- /home/mdroth/w/qemu4.git/scripts/texi2pod.pl -I docs -I 
/home/mdroth/w/qemu4.git -I . -DVERSION="4.0.50" 
-DCONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" 
/home/mdroth/w/qemu4.git/qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8 
--section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8
CONFDIR="/home/mdroth/w/qemu-install2/etc/qemu" sphinx-build  -W -n -b man -D 
version=4.0.50 -D release="4.0.50 (v4.0.0-1240-g90b8a170d2-dirty)" -d 
.doctrees/interop /home/mdroth/w/qemu4.git/docs/interop docs/interop
Running Sphinx v1.6.7
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [config changed] 7 added, 0 changed, 0 removed
reading sources... [ 14%] bitmaps
reading sources... [ 28%] index
reading sources... [ 42%] live-block-operations
reading sources... [ 57%] pr-helper
reading sources... [ 71%] qemu-ga
reading sources... [ 85%] vhost-user
reading sources... [100%] vhost-user-gpu

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... qemu-ga.8 { }
build succeeded.

> 
> I've just realized that I didn't also update the 'build-manual'
> macro to add the CONFDIR setting. Perhaps Sphinx ran first with
> the build-manual macro and has cached document contents created
> with that incorrect invocation and then reused them in the manpage
> creation? If so, this should be fixable by adding the 
> CONFDIR="$(qemu_confdir)"
> to the build-manual macro in the Makefile, and then deleting the .doctrees/
> directory from your build tree and rerunning make.

Sorry looks like it was an issue on my end actually...I guess I had a left-over
.doctrees from an earlier build (with no --prefix). I generally rm -rf * within
build directory instead of 'make clean', but that was still leaving around a
stale .doctrees. Once I deleted that I could no longer reproduce (neither
with/without the additional CONFDIR setting).

> 
> > Sphinx seems to do a better job of formatting "Key" and "Key type" into
> > actual table columns in the generated man/html pages (rather than just
> > separating them with whitespace), so I think we can drop the trailing '='s
> 
> Sure; I'll change this in v2.
> 
> thanks
> -- PMM
>