On Thu, 13 Jun 2019 at 16:20, Michael Roth <mdr...@linux.vnet.ibm.com> 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 <peter.mayd...@linaro.org>
> > +# 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
