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

[Daniel P . Berrangé]

On Thu, Jan 24, 2019 at 06:56:09PM +0000, Peter Maydell wrote:
> I had another look this afternoon at building our rST docs
> with sphinx-build. In particular, we currently have some
> docs in rst format, but we're not building them into HTML
> or shipping them. (Predictably, this means a few errors and
> warnings have crept in...)
> 
> I had a play about with adding some makefile runes, but
> I'm not sure entirely what I should be aiming for.
> 
> (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.

Of course I do agree that we should be a enabling sphinx-build
during any of our CI builds so that we catch badly formatted
.rst docs. In addition I think much of docs/ could be useful
published on qemu.org.

> (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 think 'make install-doc' should ship stuff that is useful
to end users of QEMU. This would be man pages, usage guides,
application developer information, etc.

It would not include anything that's related to the internals
of QEMU, as that's targetted at QEMU's developers themselves.

In Fedora we would not care to ship any docs that are targetting
QEMU developers, since those people would not be likely to be
using distro packaged QEMU.

> 
> (3) Indexes, table-of-contents pages, etc
> Are we aiming to ship these?
> I think that we probably want to have what from
> Sphinx's point of view are multiple separate documents,
> so that they each get their own ToC and index. This
> means we can for instance ship the ToC/index for
> the user docs but not have it contain index entries
> for developer docs.
> 
> Overall what I'm hoping for is to be able to get some
> basic structure/building commands into master so we
> have a framework and something we can iterate on to
> move forward.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|