Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1410160

Re: [PATCH 00/10] Documentation/Sphinx

Show all headers | View raw

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

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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 08/10] Documentation: add kernel hacking rst Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 03/10] Documentation/sphinx: add basic working Sphinx configuration and build Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 09/10] Documentation: add kernel api rst Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 04/10] Documentation: add .gitignore Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 02/10] kernel-doc: support printing exported and non-exported symbols Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 05/10] Documentation/sphinx: add Sphinx kernel-doc directive extension Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
    Re: [PATCH 05/10] Documentation/sphinx: add Sphinx kernel-doc  directive extension Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:40 +0200
      Re: [PATCH 05/10] Documentation/sphinx: add Sphinx kernel-doc directive extension Markus Heiser <markus.heiser@darmarit.de> - 2016-06-04 09:00 +0200
  [PATCH 06/10] Documentation/sphinx: configure the kernel-doc extension Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 07/10] sphinx: cheesy script to convert .tmpl files Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  [PATCH 01/10] kernel-doc: fix use of uninitialized value Jani Nikula <jani.nikula@intel.com> - 2016-05-20 15:50 +0200
  Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-29 22:40 +0200
    Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-05-30 11:20 +0200
      Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-30 12:50 +0200
        Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-30 16:50 +0200
          Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-05-30 17:30 +0200
          Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-30 18:50 +0200
            Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-30 22:10 +0200
              Re: [PATCH 00/10] Documentation/Sphinx Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-05-30 23:30 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-31 12:20 +0200
              Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-31 09:30 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-05-31 10:10 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-31 11:50 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-05-31 12:40 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Markus Heiser <markus.heiser@darmarit.de> - 2016-05-31 13:20 +0200
              Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:50 +0200
                Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Markus Heiser <markus.heiser@darmarit.de> - 2016-06-07 08:10 +0200
                Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Jani Nikula <jani.nikula@intel.com> - 2016-06-07 08:50 +0200
                Re: rst2pdf (was [PATCH 00/10] Documentation/Sphinx) Markus Heiser <markus.heiser@darmarit.de> - 2016-06-10 19:10 +0200
              Re: [PATCH 00/10] Documentation/Sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-03 23:10 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-06-04 01:00 +0200
                Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-04 13:50 +0200
      Re: [PATCH 00/10] Documentation/Sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-01 03:10 +0200
        Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-06-01 08:50 +0200
  Re: [PATCH 00/10] Documentation/Sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:20 +0200
    Re: [PATCH 00/10] Documentation/Sphinx Jonathan Corbet <corbet@lwn.net> - 2016-06-03 22:30 +0200
      Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-04 15:10 +0200
    Re: [PATCH 00/10] Documentation/Sphinx Daniel Vetter <daniel.vetter@ffwll.ch> - 2016-06-03 22:30 +0200
    Re: [PATCH 00/10] Documentation/Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-04 15:00 +0200

csiph-web