On Tue, Sep 25, 2018 at 11:15:05AM +0100, Peter Maydell wrote: > On 25 September 2018 at 09:58, Kashyap Chamarthy <kcham...@redhat.com> wrote: > > > Currently what I have is the 10 documents from the docs/ directory that > > are convereted to rST (some of them are already in QEMU Git); the below > > rendering is built from QEMU 3.0): > > https://kashyapc.fedorapeople.org/QEMU-Docs/_build/html/ > > Did you need to make changes to the qemu git tree (sphinx > config files, etc) to do that, or is it simply "hand run > sphinx on the rst files, publish them" ?
It's the latter -- hand-run Sphinx on the rST files. You can see the slightly modified 'conf.py' (you have to download it; can't view in the browser) and 'Makefile' (IIRC, unmodified) if you traverse two directories backwards: https://kashyapc.fedorapeople.org/QEMU-Docs/. To produce that, I just ran the `sphinx-quickstart` (the documentation template generator) from a shell, which asks a bunch of questions (it can be automated, of course); then it creates all the necessary files: conf.py, index.rst, Makefile, et al. And once you have the docs/ directory populated, update the 'toctree', then it's a trivial `make html`. > > Given the complexity and breadth of QEMU, it's easy to imagine more than > > a full-time role for high-quality user and developer documentation. As > > you need to spend time soaking into the code, actively follow the > > upstream mailing list(s), try patch sets while they're in flux, write > > test programs, and _then_ there is the "small matter of detailed > > documentation". Reminds me of the inimitable Michael Kerrisk of Linux > > 'man-pages'. > > Definitely. I think what we should aim for to start with is to > have the basic framework in place (so that for instance we do > build the rst files in docs/ into html which we ship/publish). > I think it's easier for people to make contributions to improving > the docs if they're just putting another brick into a pre-existing > framework, rather than having to tackle the structural issues first. Yeah, very true; you articulate the issue more clearly. -- /kashyap
