Re: [PATCH 00/10] Documentation/Sphinx

From	Jani Nikula <jani.nikula@intel.com>
Newsgroups	linux.kernel
Subject	Re: [PATCH 00/10] Documentation/Sphinx
Date	2016-05-31 12:40 +0200
Message-ID	<rEPfA-1vx-35@gated-at.bofh.it> (permalink)
References	(5 earlier) <rEyy6-6IE-47@gated-at.bofh.it> <rEBFD-B5-21@gated-at.bofh.it> <rEMhI-7Yx-5@gated-at.bofh.it> <rEMUq-73-23@gated-at.bofh.it> <rEOtb-XL-13@gated-at.bofh.it>
Organization	Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo

Show all headers | View raw

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

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