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

Groups > linux.kernel > #1410095

Re: [PATCH 00/10] Documentation/Sphinx

Path csiph.com!1.us.feeder.erje.net!feeder.erje.net!2.eu.feeder.erje.net!weretis.net!feeder1.news.weretis.net!feeder4.news.weretis.net!news.mixmin.net!aioe.org!gothmog.csi.it!bofh.it!news.nic.it!robomod
From Jani Nikula <jani.nikula@intel.com>
Newsgroups linux.kernel
Subject Re: [PATCH 00/10] Documentation/Sphinx
Date Tue, 31 May 2016 12:40:02 +0200
Message-ID <rEPfA-1vx-35@gated-at.bofh.it> (permalink)
References <rASYp-68P-3@gated-at.bofh.it> <rEfF8-2Ag-7@gated-at.bofh.it> <rErwD-2fk-55@gated-at.bofh.it> <rEsVI-2ZZ-11@gated-at.bofh.it> <rEwFX-5sh-3@gated-at.bofh.it> <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>
X-Extloop1 1
X-Ironport-Av E=Sophos;i="5.26,395,1459839600"; d="scan'208";a="992113333"
Organization Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo
User-Agent Notmuch/0.22+12~gbdd9442 (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu)
MIME-Version 1.0
Content-Type text/plain
Sender robomod@news.nic.it
List-ID <linux-kernel.vger.kernel.org>
X-Mailing-List linux-kernel@vger.kernel.org
Approved robomod@news.nic.it
Lines 39
X-Original-Cc Jonathan Corbet <corbet@lwn.net>, Grant Likely <grant.likely@secretlab.ca>, Mauro Carvalho Chehab <mchehab@osg.samsung.com>, Dan Allen <dan@opendevise.io>, Russel Winder <russel@winder.org.uk>, Keith Packard <keithp@keithp.com>, LKML <linux-kernel@vger.kernel.org>, linux-doc@vger.kernel.org, Hans Verkuil <hverkuil@xs4all.nl>
X-Original-Date Tue, 31 May 2016 13:30:32 +0300
X-Original-Message-ID <87twhea59z.fsf@intel.com>
X-Original-References <cover.1463748027.git.jani.nikula@intel.com> <877fec7gfm.fsf@intel.com> <CAKMK7uGSwf_jd2Nys=yArmA6voGmbyfTP4UAibswT4rU6yi75Q@mail.gmail.com> <36300F5F-C3F3-4A55-9257-788CF9F96CA4@darmarit.de> <878tyrbo36.fsf@intel.com> <5369C8B8-47F2-4B67-A314-5EB5471ABA00@darmarit.de> <87k2ibfh0x.fsf@intel.com> <6A6202B8-16E4-4EC0-9528-A79FB703FFCD@darmarit.de> <CAKMK7uGd=oMO0Da-67r5G7r4bbS2PpXO2qwzK=TozF2Vp=Sc_w@mail.gmail.com> <FFCBE388-95A4-4A40-876B-DC8C689CE52E@darmarit.de>
X-Original-Sender linux-kernel-owner@vger.kernel.org
Xref csiph.com linux.kernel:1410095

Show key headers only | 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

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