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

[Cornelia Huck <cohuck@redhat.com>]

On Thu, 13 Feb 2020 18:54:37 +0000
Peter Maydell <peter.maydell@linaro.org> wrote:

> On Thu, 13 Feb 2020 at 18:38, Pierre Morel <pmorel@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.)