Re: [PATCH v2 2/2] docs: rstfy vfio-ap documentation

[Peter Maydell]

On Thu, 13 Feb 2020 at 18:38, Pierre Morel <address@hidden>
wrote:> However it may be because I do not use the right tools.
> Did not find which one I am suppose to use.
> Currently using:
> rst2latex vfio-ap.rst > vfio-ap.tex && pdflatex vfio-ap.tex

The only supported way to build the docs is with Sphinx.

Option 1:

If you have the right versions of the tools installed
then running "make" in the usual way will build HTML docs
into the docs/ subdirectory of your build directory.
Passing --enable-docs to configure will cause it to complain
if you're missing a tool rather than silently not building
the docs. This is what we expect most users to be doing.

Option 2:

You can run Sphinx 'manually' with something like
 sphinx-build docs /tmp/sphinx-out
which will build a single big fat manual into the
specified output directory (here /tmp/sphinx-out).
This option is provided mostly so that sites like
'readthedocs' can produce the documentation without having
to run our Makefiles.

PDF is not an officially supported (by us) output format,
but if you really want it you can generate it with
 sphinx-build -b latex docs /tmp/sphinx-out
 cd /tmp/sphinx-out
 make
which will generate a QEMU.pdf in /tmp/sphinx-out.

We're unlikely to want to make tweaks to the documentation
sources to fix infelicities in the formatting of the PDF,
though.

thanks
-- PMM