Re: [PATCH] build: Build and install the info manual.

[Peter Maydell]

On Sun, 27 Sep 2020 at 03:21, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
> Peter Maydell <peter.maydell@linaro.org> writes:
> > It is the best way we found for getting Sphinx to do what we wanted.
> > I agree that it would be nicer to have one manual with all the user
> > facing parts in it, but it is apparently not possible to do that without
> > shipping the devel docs to users, which we didn't want to do.
>
> I personally don't understand the rationale of hiding the devel section
> from users, especially given the kind of users QEMU is likely to attract
> (e.g, teksavvy people, perhaps themselves developers that could be
> curious peeking into that section to deepen their understanding of
> QEMU's architecture and internals).

Mostly I think we came to this opinion because
(a) it was how we handled developer docs before -- they tended
to be standalone files in docs/ somewhere, not part of the
old shipped-to-user Texinfo docs
(b) internals docs are much more likely to become quickly outdated:
you almost always want to be looking at the docs for current-git,
not for some older distro-installed QEMU version
(c) sure, some users might want to look at QEMU internals docs,
but they are definitely going to be the minority
(d) the developer docs are rougher in quality overall
(e) you need the source tree anyway if you're interested in
the internals, because so much is not documented, or not in
the rST manuals

That said, we are kind of working against the grain of how
Sphinx wants to be used here, which is usually not a great idea,
and it does result in some awkwardnesses (it would be nice to
have the devel docs on the qemu.org website, for instance).
I asked around on IRC and nobody seemed to be very strongly
against moving to the just-one-manual setup. So maybe we should
do that.

thanks
-- PMM