From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:57705) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3yYf-0004t8-M9 for qemu-devel@nongnu.org; Tue, 08 Nov 2016 00:02:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3yYc-0000vv-Hc for qemu-devel@nongnu.org; Tue, 08 Nov 2016 00:02:53 -0500 Received: from out4-smtp.messagingengine.com ([66.111.4.28]:43186) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c3yYc-0000vD-Cy for qemu-devel@nongnu.org; Tue, 08 Nov 2016 00:02:50 -0500 Date: Tue, 8 Nov 2016 00:02:42 -0500 From: "Emilio G. Cota" Message-ID: <20161108050242.GA23110@flamenco> References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Subject: Re: [Qemu-devel] Sphinx for QEMU docs? (and a doc-comment format question) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Peter Maydell Cc: QEMU Developers , Paolo Bonzini , Stefan Hajnoczi On Mon, Nov 07, 2016 at 15:03:23 +0000, Peter Maydell wrote: > On 5 November 2016 at 18:42, Peter Maydell wrote: > > With a little luck I may be able to put something up > > on Monday as a sort of minimal-demonstration of how > > this would look in QEMU. > > Generated documentation: > http://people.linaro.org/~peter.maydell/sphinx/index.html > Git branch with the patches needed to produce that: > https://git.linaro.org/people/peter.maydell/qemu-arm.git sphinx-docs > Pointy-clicky interface to git branch: > https://git.linaro.org/people/peter.maydell/qemu-arm.git/log/?h=sphinx-docs > > I didn't bother to write the makefile changes to tie it into > the main build process, so to regenerate the docs locally you'll > need to run > sphinx-build -b html docs my-build-dir/docs > from the QEMU source tree root, which will put the output into > my-build-dir/docs, which you can then point your web browser at. I moved qht's documentation to this to see how hard it was. Was trivial to do! The result looks very nice. Patches here: - Web: https://github.com/cota/qemu/tree/sphinx-docs - Git: https://github.com/cota/qemu.git sphinx-docs > The overall organisation structure needs some thought -- > I think we should at least separate into user/ for user > docs and dev/ for internals docs (and only install the > user/ docs). Agreed. > The branch above just puts the two example > docs directly into the index.rst for demo purposes. > > Conclusions from this exercise: > 1) conversion isn't all that difficult, and the results > look pretty nice > 2) some of the doc-comment format differences are irritating: > . "function - short description" not "function: short description" > . "&struct.fieldname" not ".@fieldname" > . "&typename" not "#typename" > 3) the most awkward part of kernel-doc syntax is that it bakes > in the kernel's style choice of always using "struct foo" > for types -- I don't think there's any way to document > 'MemoryRegion' and 'AddressSpace' without the 'struct' > coming out in the documentation output. > > We could fix (2) by loosening the kernel-doc script's > parsing if we were happy to carry around a forked version > of it. Fixing (3) requires more serious surgery on kernel-doc > I suspect. FWIW I'd prefer to strictly adhere to kerneldoc as is. Converting the existing kerneldocs will require some supervision, anyway. E.