Re: [PATCH 00/10] Documentation/Sphinx

[Markus Heiser]

Am 31.05.2016 um 10:07 schrieb Daniel Vetter <daniel.vetter@xxxxxxxx>:

> On Tue, May 31, 2016 at 9:27 AM, Markus Heiser
> <markus.heiser@xxxxxxxxxxx> wrote:
>>>>> I find it totally unacceptable to require explicitly marking kernel-doc
>>>>> comments or source files as being reStructuredText.
>>>>> Note that it's all opt-in already. If you add a .rst file that includes
>>>>> kernel-doc via the kernel-doc extension, you better make sure the
>>>>> comments parse as reStructuredText and render nicely. I'm willing to do
>>>>> much of the job for all the things that I care about.
>>>> 
>>>> We have a different POV ... I try to build up a documentation project,
>>>> which could use all given kernel-doc markups without any change, where
>>>> reST is an "addition". Your approach is to fix kernel-doc comments
>>>> if they are referred by a kernl-doc directive in a .rst document.
>>>> There is nothing wrong about your approach, but I try to build
>>>> a whole source code documentation like the one I started here:
>>>> http://return42.github.io/sphkerneldoc/linux_src_doc/index.html
>>> 
>>> That looks nice, but I'll argue it would not be much worse even if you
>>> assumed it's all rst.
>> 
>> A superficial look on the HTML output may give the impression. But in
>> the log you will find tons of errors and warnings. My experience is,
>> that authors will not consult logs if there are tons of errors from the
>> beginning, which carries a decrease in quality. IMO not a good starting
>> point.
> 
> 0-day builds all docs, and checks for new warnings. Even in today's
> gpu.tmpl build there's a massive pile of warnings, so yes developers
> don't look. But 0-day does, and then developers look at the nice mails
> from 0-day. It mostly works to keep out new fail I think.

In general, I'am not very happy with workarounds like this. IMO these
are workarounds are often, rewards bunglers and punish those with more work,
who want make thinks right. There might be situations where 0-day build
is the only/best solution. But *here* we are talking about one additional
comment line the author adds, when he modify his source comments from kernel-doc 
to reST markup .. IMO not very hard.

This one line helps the doc-builder to distinguish between *vintage* kernel-doc
comments and those with reST additions in.

With the announcement of the markup, we can use all existing kernel-doc
markups "as is" for building a complete src-code documentation, with
thousands of errors less in the log (experience from my POC). IMO a great
benefit ... given by just one additional comment line to distinguish between
vintage and reST ... 

BTW it's is not uncommon to announce the markup in projects with mixed 
markups in the source code comments.


     A few words about my point of view / my thought:

I strict separate markup from the doc-building tools. The decision in favor for
reST is not done because sphinx-doc is a great doc-bulding tool, it is done because
reST is a easy to write / read markup with a clear and expressive syntax definition.
The *best* builder for this markup is sphinx-doc, so it is only natural, that
the decision for the builder falls to sphinx-doc.

But kernel documentation is not a project from scratch, there was the *vintage*
kernel-doc markup first. Therefore, reST is only an additional markup!

With this POV you can add reST (or any other) markup to the doc-building process.
The Linux kernel draws on diverse projects, some of them may use different
markups and these maintainers are not interested in changing there whole markup
when they contribute to the kernel ... but may be there is someone how want's 
to add an other additional markup support to the doc-building process.

I'am not interested in supporting additional markups beside reST. But this is a
scalable future-proof solution, which only needs an announcement of the the markup.
The one additional comment line we are talking about.

--Markus--

> -Daniel
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> +41 (0) 79 365 57 48 - http://blog.ffwll.ch