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

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Hello Peter,

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

> On Sun, 27 Sep 2020 at 03:21, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

[...]

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

OK.  Thanks for asking others if they had an opinion about it.  Given
they don't seem to feel strongly about it, I suggest:

1) Keep the developer section as the last section of the overall doc
table of content (as was done in my original patch).

2) Mark the top level couple orphaned .rst as "orphaned" as proposed in
one of my previous reply, since this is what they are.  They will get
built, but won't appear anywhere in the QEMU documentation.

If that sounds reasonable, I'll send an updated patch soon.

Another thing; there was some CI failures with the origin patches I
sent [0]; are they worth investigating or are they unrelated, "known"
failures?

Thanks,

Maxim

[0]  https://patchew.org/QEMU/20200925024143.26492-1-maxim.cournoyer@gmail.com/