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

[Peter Maydell]

On Tue, 29 Jan 2019 at 10:36, Daniel P. Berrangé <address@hidden> 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).
>
> Currently in Fedora RPMs we ship the man pages and the
> qemu-doc.html, qemu-ga-ref.html & qemu-qmp-ref.html files.
> I'm not really seeing stuff in docs/ that grabs me as very
> important to ship to users in Fedora RPMs. In fact I rather
> doubt anyone even looks at the HTML files we currently
> ship in the RPMs, as opposed to just looking in QEMU git.
> Aside from man pages, I imagine most users just turn to
> Google and/or qemu.org to find QEMU docs, not look inside
> the distro packages.
>
> IOW from a distro POV I think I'd probably find sphinx-build
> to be an undesirable mandatory dep.

The idea is that we would be aiming to transition all the
info that is currently in the other docs over to rST docs
(and also improve on the rST docs), i.e. we would want to
dump the current texinfo tooling eventually. It's true that
as build dep it doesn't bring much extra to the table to
start with, but that should change over time.

Is sphinx-build particularly nasty as a build-dep for distros,
or is it just "don't really want to add another thing" ?

thanks
-- PMM