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 >
