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

[Peter Maydell]

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 ?

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.

> 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