qemu-devel
[Top][All Lists]
Advanced

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

Re: [Qemu-devel] building rst docs with sphinx


From: Cole Robinson
Subject: Re: [Qemu-devel] building rst docs with sphinx
Date: Tue, 29 Jan 2019 09:39:20 -0500
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.4.0

On 1/28/19 9:18 PM, Stefan Hajnoczi wrote:
On Thu, Jan 24, 2019 at 06:56:09PM +0000, Peter Maydell wrote:
(1) configure: My thought is that we should just make
sphinx-build a requirement for the existing --enable-docs
switch (as texinfo and pod2man are currently). The
disadvantage is that we won't support a "build the half
of the docs you have the tools for and leave the others"
setup. The advantage, which I think is significant, is that
distros will naturally be directed to the missing build
dependency (either they're building with --enable-docs
and will get the configure message, or they aren't and
then their build will fail later because of missing docs
files when they try to put the built files into the package).

I'm CCing Cole (Fedora) and the Debian QEMU team so they can give their
input on this point and your next point.


Peter's assessment sounds correct to me. And sphinx is so widely available that adding it as a build dep is no problem at all IMO

(2) What do we actually want to ship?
That is, what do we want 'make install-doc' to copy into
the installation directory?
https://wiki.qemu.org/Features/Documentation
has a good suggested breakdown of docs for where we
eventually want to be. I think we probably don't want
to install the "developer's guide" (docs/devel) on
end-user systems. The others are presumably OK.
Currently, we seem to only install manpages and a
few other things in the 'install-doc' makefile target
(we don't install a bunch of plain-text user-facing
docs) so this would be a significant expansion.

I agree, developer documentation is not relevant to end-users.


Agreed as well. On my Fedora system I see that some packages install HACKING/CONTRIBUTING files but even that seems a little weird. If qemu cared about installing developer docs it could be a separate makefile target so it's easy to control whether it's handled during package build

Thanks,
Cole



reply via email to

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