Em Tue, 20 Sep 2016 20:56:35 +0200
Markus Heiser <markus.hei...@darmarit.de> escreveu:
> > If I understood it right, I could do something like:
> > diff --git a/Documentation/media/conf_nitpick.py
> > b/Documentation/media/conf_nitpick.py
> > index 480d548af670..2de603871536 100644
> > --- a/Documentation/media/conf_nitpick.py
> > +++ b/Documentation/media/conf_nitpick.py
> > @@ -107,3 +107,9 @@ nitpick_ignore = [
> > ("c:type", "v4l2_m2m_dev"),
> > ]
> > +
> > +
> > +extensions.append("linuxdoc.rstKernelDoc")
> > +extensions.append("linuxdoc.rstFlatTable")
> > +extensions.append("linuxdoc.kernel_include")
> > +extensions.append("linuxdoc.manKernelDoc")
> > Right?
> No ;)
> > It would be good to do some sort of logic on the
> > above for it to automatically include it, if linuxdoc is
> > present, otherwise print a warning and do "just" the normal
> > Sphinx tests.
> The intention is; with installing the linuxdoc project you get
> some nice command line tools, like lint for free and if you want
> to see how the linuxdoc project compiles your kernel documentation
> and how e.g. man pages are build or what warnings are spit, you
> have to **replace** the extensions from the kernel's source with
> the one from the linuxdoc project.
> This is done by patching the build scripts as described in:
> FYI: I updated the documentation of the linuxdoc project.
Hmm... It would be a way better to just do something like the
above patch, specially since a conf_lint.py could have the
modified conf_nitpick.py, and avoiding touching at the
tree. The need of making a patch to use it, touching at the
building system prevents it to be called for every applied
patch that would touch on a documented header file.
I used the above to detect some cut-and-paste issues with some
Yet, from what I saw, the parsers of lint still need some work,
as it didn't parse some stuff at the media headers that seem ok.
> In this project I develop and maintain "future" concepts like
> man-page builder and the py-version of the kernel-doc parser.
The new parser seems to have some bugs, like those:
$ kernel-lintdoc include/media/v4l2-ctrls.h
include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not marked as
typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
include/media/v4l2-ctrls.h:605 :WARN: typedef of function pointer not marked as
typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
include/media/v4l2-ctrls.h:809 [kernel-doc WARN] : can't understand function
proto: 'const char * const *v4l2_ctrl_get_menu(u32 id);'
in this case, both typedefs were defined. The prototype for
v4l2_ctrl_get_menu() is also valid.
Anyway, it helped to get some real troubles. Thanks!
> Vice versa, every improvement I see on kernel's source tree is
> merged into this project.
> This project is also used by my POC at:
> * http://return42.github.io/sphkerneldoc/
> E.g. it builds the documentation of the complete kernel sources
> * http://return42.github.io/sphkerneldoc/linux_src_doc/index.html
> the last one is also my test-case to find regression when I change
> something / running against the whole source tree and compare the
> result to the versioned reST files at
> * https://github.com/return42/sphkerneldoc/tree/master/doc/linux_src_doc
> -- Markus --
> >> E.g. if you want to lint your whole include/media tree type:
> >> kernel-lintdoc [--sloppy] include/media
> > Yeah, running it manually is another way, although I prefer to have
> > it done via a Makefile target, and doing only for the files that
> > are currently inside a Sphinx rst file (at least on a first moment).
> > Thanks,
> > Mauro
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html