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

[Cole Robinson <crobinso@redhat.com>]

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