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