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

[Cole Robinson]

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