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

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Wed, 11 Mar 2020 at 14:53, Markus Armbruster <armbru@redhat.com> 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).

I missed this part.  Not your fault.

> 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.

I see.

With plain text gone, I'll certainly look at any of the rendered stuff
even less than before.

Would it be possible to additionally render a complete manual as one
humongous .html?  Without an index, there's only search, and the
ergonomics of searching within a single page are so much better.

I'm tempted to write a trivial QAPI doc comment backend to spit out
minimally processed doc comments as one plain text file just for that.