Re: [PATCH v3 31/33] docs: Stop building qemu-doc

[Peter Maydell]

On Wed, 11 Mar 2020 at 14:53, Markus Armbruster <address@hidden> wrote:
> This appears to lose plain text, PDF and info output.  Any chance to get
> plain text back?

This is deliberate. Consensus when we decided on the docs
transition plan was that plain text was not a useful output
format. (discussed in
https://lists.gnu.org/archive/html/qemu-devel/2019-05/msg04932.html
and following thread).

Sphinx does support text file generation, so you can if
you really want it generate it with something like
 sphinx-build docs /tmp/docs-out -b text
but:
 * it produces one text file per input file, so you might
as well just read the rST sources
 * at least in the version of Sphinx I have, the text builder
does not implement some of the table markup we use,
so it will fall over partway with a NotImplementedError

PDF similarly is in theory possible via 'latex' builder
(and then running LaTeX on the results). You can also
download a PDF from
https://readthedocs.org/projects/qemu/downloads/
You will find that there are some bits where rendering
is not good (eg long lines that didn't get wrapped so were
just truncated).

Personally I think it's difficult enough managing two
output formats and checking that they look reasonable
(we already found places in the QAPI docs where
clearly nobody had looked at *any* of the rendered
formats) so I think settling on "our supported document
formats are HTML and manpage" is reasonable.

thanks
-- PMM