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