Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Date:   Fri, 26 Apr 2019 14:54:24 -0300
From:   Mauro Carvalho Chehab <mchehab@kernel.org>
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     Jani Nikula <jani.nikula@linux.intel.com>,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Matthew Wilcox <willy@infradead.org>
Subject: Re: [PATCH 1/2] Docs: An initial automarkup extension for sphinx
Message-ID: <20190426145424.268da5df@coco.lan>
In-Reply-To: <20190426105209.1e414eae@lwn.net>
References: <20190425200125.12302-1-corbet@lwn.net>
        <20190425200125.12302-2-corbet@lwn.net>
        <87tvelrv8d.fsf@intel.com>
        <20190426105209.1e414eae@lwn.net>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Em Fri, 26 Apr 2019 10:52:09 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 26 Apr 2019 12:06:42 +0300
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
> > It's more involved, but I think the better place to do this (as well as
> > the kernel-doc transformations) would be in the doctree-read event,
> > after the rst parsing is done. You can traverse the doctree and find the
> > places which weren't special for Sphinx, and replace the plain text
> > nodes in-place. I've toyed with this in the past, but alas I didn't have
> > (and still don't) have the time to finish the job.  
> 
> I had thought about this; indeed, there's a comment in the posted patch to
> that effect.  The tradeoff comes down to this, I think:
> 
>  - The fragility and inelegance of embedding a bit of redundant RST
>    parsing into this extension v. that of adding a late parsing stage as a
>    transform, trying to enumerate every node type that you might want to
>    change, and digging into the C domain code to emulate its reference
>    generation.
> 
>  - The time required to implement a solution; I'm having a bit of a hard
>    time keeping up with docs at the moment as it is.
> 
>  - Regexes.  This solution has more of them, but we're not going to get
>    away from them regardless.
> 
> I am not at all opposed to a more proper solution that might, in the
> long term, produce more deterministic results.  I can even try to work in
> that direction.  But this is something that can be done now that, IMO,
> doesn't in any way close off a better implementation in the future.  If we
> agree that we should automatically generate references for occurrences of
> "function()", we can change how that is actually done later.
> 
> I'll look into this further, but my inclination is to go forward with what
> I have now.  It's simple and easy to understand, and doesn't seem to screw
> up anywhere in the current body of kernel docs as far as I can tell.
> 
> > If you decide to go with regex anyway, I'd at least consider pulling the
> > transformations/highlights from kernel-doc the script to the Sphinx
> > extension, and use the exact same transformations for stuff in source
> > code comments and rst files.  
> 
> Pulling all RST manipulation out of kerneldoc has a great deal of appeal;
> assuming this goes forward that should indeed be high on the todo list.

While I didn't review the python code yet, and while I agree with
Jani and Markus that it would be better only parse functions on texts
after the Sphinx parser, I agree with Jon on that: if the current code works
well enough with the current documentation, I would proceed and apply it. 

Later, the script can be improved.

Thanks,
Mauro