On Thu, 13 Feb 2020 18:54:37 +0000 Peter Maydell <peter.mayd...@linaro.org> wrote:
> On Thu, 13 Feb 2020 at 18:38, Pierre Morel <pmo...@linux.ibm.com> > 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.)
