From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:51532) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c3smR-0007MZ-8G for qemu-devel@nongnu.org; Mon, 07 Nov 2016 17:52:44 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c3smO-0001OH-6j for qemu-devel@nongnu.org; Mon, 07 Nov 2016 17:52:43 -0500 Received: from mx1.redhat.com ([209.132.183.28]:45626) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1c3smN-0001OB-Vv for qemu-devel@nongnu.org; Mon, 07 Nov 2016 17:52:40 -0500 References: <20161107133045.GM5036@stefanha-x1.localdomain> From: John Snow Message-ID: Date: Mon, 7 Nov 2016 17:52:37 -0500 MIME-Version: 1.0 In-Reply-To: <20161107133045.GM5036@stefanha-x1.localdomain> Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit 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: Stefan Hajnoczi , Peter Maydell Cc: Paolo Bonzini , QEMU Developers , Stefan Hajnoczi On 11/07/2016 08:30 AM, Stefan Hajnoczi wrote: > On Sat, Nov 05, 2016 at 06:42:23PM +0000, Peter Maydell wrote: >> In particular I think we could: >> * set up a framework for our in-tree docs/ which gives us a >> place to put new docs (both for-users and for-developers) -- >> I think having someplace to put things will reduce the barrier >> to people writing useful new docs >> * gradually convert the existing docs to rst >> * use the sphinx extension features to pull in the doc-comments >> we have been fairly consistently writing over the last few years >> (for instance a converted version of docs/memory.txt could pull >> in doc comments from memory.h; or we can just write simple >> wrapper files like a "Bitmap operations" document that >> displays the doc comments from bitops.h) > > You are suggesting Sphinx for two different purposes: > > 1. Formatting docs/ in HTML, PDF, etc. > > 2. API documentation from doc comments. > > It's a good idea for #1 since we can then publish automated builds of > the docs. They will be easy to view and link to in a web browser. > > I'm not a fan of #2. QEMU is not a C library that people develop > against and our APIs are not stable. There is no incentive for pretty > doc comments. It might be cool to set it up once but things will > deterioate again quickly because we don't actually need external API > docs. > > Instead of #2 we should focus on generating nice external QMP docs for > libvirt and other clients. That has a clear benefit. > > Stefan > I think that designating certain interfaces within QEMU as "Internal API" has some merit and are worth documenting for the sake of device/format authors like Peter suggests. Things may be in flux often, but if we can generate the docs from source code comments, I don't think it's unjust or unreasonable to request that patches keep these docs up to date. It's error prone, of course, but certainly more manageable if we have a build tool doing some robotic checking of doc completeness for select interfaces. I think it's not possible to be more error prone than our current solution of "Random GTK-doc-like comments strewn about that may or may not be accurate, that we don't actually check or verify or even use for any doc-building purposes." I'm also a fan of unifying our internal code documentation formats because it helps make the code look more consistent, but may also open up some parsing options for enhanced IDE support which could be nice for some. I think at a minimum, having _A_ standard approach cannot possibly be *any* worse than _NO_ standard approach. I'm a fan of the concept, but have no particular feelings on Sphinx yet. --js