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

[Philippe Mathieu-Daudé]

Hi Peter,

On 1/24/19 7:56 PM, 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...)

Are you talking about the files in docs/ such docs/devel/testing.rst?

Or about documention within the source files?
If so, is that the format you are talking about?

https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain

'''
The C domain (name c) is suited for documentation of C API.

.. c:function:: function prototype

    Describes a C function. The signature should be given as in C, e.g.:

    .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type,
Py_ssize_t nitems)
'''

> 
> 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).
> 
> (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.
> 
> (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.
> 
> thanks
> -- PMM
>