lkml.org 
[lkml]   [2016]   [May]   [31]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
SubjectRe: [PATCH 00/10] Documentation/Sphinx
Date
On Tue, 31 May 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 31.05.2016 um 10:07 schrieb Daniel Vetter <daniel.vetter@ffwll.ch>:
>> 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.

That "one line" translates to nearly 50000 kernel-doc comments in more
than 6000 files. If you expect people to add a tag in each file/comment,
it will never happen. If we assume it's all rst, we can at least start
converting.

I quickly wrote a small "kernel-doc-rst-lint" script (70 lines of
python) based on rst-lint [1] that runs kernel-doc on a file and reports
all the kernel-doc and rst-lint errors in the output. This can be run as
a "checker" in the kernel build with

$ make CHECKER=scripts/kernel-doc-rst-lint C=1

and it can provide better and more direct warnings on kernel-doc/rst
errors than a full Sphinx build does.

BR,
Jani.


[1] https://pypi.python.org/pypi/restructuredtext_lint



--
Jani Nikula, Intel Open Source Technology Center

\
 
 \ /
  Last update: 2016-05-31 12:41    [W:0.097 / U:0.492 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site