Re: [PATCH 00/10] Documentation/Sphinx

[Markus Heiser]

Am 31.05.2016 um 12:30 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:

> On Tue, 31 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
>> Am 31.05.2016 um 10:07 schrieb Daniel Vetter <daniel.vetter@xxxxxxxx>:
>>> 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 have the impression that we misunderstand us ...

You will add this line only to these files where you have changed the 
markup from *vintage* kerenel-doc to reST. In my solution, you can
change the markup on every comment, but you don't have to .. it
is enough to add one line at the top of the file.

It's hard to describe something without an example, let my finish my
work and after this I can show it by example. Then you will see,
that the impact is less then you fear.

> 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.

I haven't tested [1], but I assume that it covers only docutils-reST not
the Sphinx-doc superset (thats might be the reason why you see less errors)
... anyway it could be convenient tool.


--Markus--

PS: I looked closer to [1], it uses the docutils puplischer ..

  from docutils.core import Publisher

with a /dev/null like stream

  document.reporter.stream = None

The errors you get from this are the same you get from a rst2xxx 
tool ...

|  >>> import restructuredtext_lint
|  >>> errors = restructuredtext_lint.lint("""
|  ... Hello World
|  ... =======
|  ... 
|  ... :ref:`label_name` 
|  ... """)
|  >>> errors[0].astext()
|  u'None:3: (WARNING/2) Title underline too short.\n\nHello World\n======='
|  >>> errors[1].astext()
|  u'None:5: (INFO/1) No role entry for "ref" in module "docutils.parsers.rst.languages.en".\nTrying "ref" as canonical role name.'

> 
> BR,
> Jani.
> 
> 
> [1] https://pypi.python.org/pypi/restructuredtext_lint
> 
> 
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center