Re: [Qemu-devel] [PATCH v6 10/25] replay: introduce breakpoint at the specified step

[Kashyap Chamarthy]

On Tue, Sep 25, 2018 at 11:15:05AM +0100, Peter Maydell wrote:
> On 25 September 2018 at 09:58, Kashyap Chamarthy <address@hidden> 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