On Thu, 13 Feb 2020 18:54:37 +0000
Peter Maydell <address@hidden> wrote:
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.
FWIW, using option 2 to produce a pdf seems to end up with something
decent-looking with these patches applied. (Lots of warnings from
LaTex, but that seems preexisting.)