[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Markus Armbruster
Subject: Re: [PATCH v3 31/33] docs: Stop building qemu-doc
Date: Thu, 12 Mar 2020 07:06:11 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux)

Peter Maydell <address@hidden> writes:

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]