From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S964837AbcEDJ66 (ORCPT ); Wed, 4 May 2016 05:58:58 -0400 Received: from mga01.intel.com ([192.55.52.88]:62002 "EHLO mga01.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933972AbcEDJ6z (ORCPT ); Wed, 4 May 2016 05:58:55 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.24,576,1455004800"; d="scan'208";a="972297361" From: Jani Nikula To: Markus Heiser , Daniel Vetter , Jonathan Corbet Cc: Grant Likely , Mauro Carvalho Chehab , Dan Allen , Russel Winder , Keith Packard , LKML , linux-doc@vger.kernel.org, Hans Verkuil , "linux-media\@vger.kernel.org linux-media" , Graham Whaley Subject: Re: Kernel docs: muddying the waters a bit In-Reply-To: <54CDCFE8-45C3-41F6-9497-E02DB4184048@darmarit.de> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20160213145317.247c63c7@lwn.net> <87y49zr74t.fsf@intel.com> <20160303071305.247e30b1@lwn.net> <20160303155037.705f33dd@recife.lan> <86egbrm9hw.fsf@hiro.keithp.com> <1457076530.13171.13.camel@winder.org.uk> <87a8m9qoy8.fsf@intel.com> <20160308082948.4e2e0f82@recife.lan> <20160308103922.48d87d9d@recife.lan> <20160308123921.6f2248ab@recife.lan> <20160309182709.7ab1e5db@recife.lan> <87fuvypr2h.fsf@intel.com> <20160310122101.2fca3d79@recife.lan> <8992F589-5B66-4BDB-807A-79AC8644F006@darmarit.de> <20160412094620.4fbf05c0@lwn.net> <54CDCFE8-45C3-41F6-9497-E02DB4184048@darmarit.de> User-Agent: Notmuch/0.21+91~gada1e33 (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Wed, 04 May 2016 12:58:49 +0300 Message-ID: <874maef8km.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 04 May 2016, Markus Heiser wrote: > but I think this will not by very helpful, as long as you miss > a similar ".tmpl" workflow for reST documents. > > I'am working on a reST directive (named: "kernel-doc") to provide a > similar ".tmpl" workflow within plain reST. The first step towards > is done with (my) modified kernel-doc script ... > > * https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc#L1736 > > which produce reST from source code comments. E.g. this content is > generated with it. What do you mean by ".tmpl workflow"? I'd be *very* hesitant about adding the kind of things you do in reformat_block_rst to kernel-doc. IMO the extraction from kernel-doc comments must be as simple as possible with basically pass-through of the comment blocks to sphinx. Specifically, do not attempt to detect and parse elements like lists in kernel-doc. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center