[PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive

[PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive

[Mike Rapoport]

Hi,

These patches allow passing "-no-doc-sections" option to scripts/kernel-doc
from the sphinx generator.

This allows to avoid duplicated DOC: sections when "kernel-doc:" directive
is used without explicit selection of functions or function types. For
instance, [1] has "IDA description" and "idr synchronization" twice.

v3 changes:
* add description for empty "functions" directive to
Documentation/doc-guide/kernel-doc.rst
v2 changes:
* Use empty "functions" directive instead of "nodocs", as per Jani's suggestion

Mike Rapoport (2):
  Documentation/sphinx: allow "functions" with no parameters
  docs/idr: use empty "functions" directive

 Documentation/core-api/idr.rst         |  2 ++
 Documentation/doc-guide/kernel-doc.rst |  9 +++++++--
 Documentation/sphinx/kerneldoc.py      | 10 +++++++---
 3 files changed, 16 insertions(+), 5 deletions(-)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters

[Mike Rapoport]

When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was explicitly
included in the same document it will be duplicated. For example, the
output generated for Documentation/core-api/idr.rst [1] has "IDA
description" in the "IDA usage" section and in the middle of the API
reference.

This patch enables using "functions" directive without parameters to output
all the documentation excluding DOC: sections.

[1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: Matthew Wilcox <willy@infradead.org>
---
 Documentation/doc-guide/kernel-doc.rst |  9 +++++++--
 Documentation/sphinx/kerneldoc.py      | 10 +++++++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
index 80383b1..8db53cd 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -488,14 +488,19 @@ doc: *title*
     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
        :doc: High Definition Audio over HDMI and Display Port
 
-functions: *function* *[...]*
+functions: *[ function ...]*
   Include documentation for each *function* in *source*.
+  If no *function* if specified, the documentaion for all functions
+  and types in the *source* will be included.
 
-  Example::
+  Examples::
 
     .. kernel-doc:: lib/bitmap.c
        :functions: bitmap_parselist bitmap_parselist_user
 
+    .. kernel-doc:: lib/idr.c
+       :functions:
+
 Without options, the kernel-doc directive includes all documentation comments
 from the source file.
 
diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index fbedcc3..9d0a7f0 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -47,7 +47,7 @@ class KernelDocDirective(Directive):
     optional_arguments = 4
     option_spec = {
         'doc': directives.unchanged_required,
-        'functions': directives.unchanged_required,
+        'functions': directives.unchanged,
         'export': directives.unchanged,
         'internal': directives.unchanged,
     }
@@ -75,8 +75,12 @@ class KernelDocDirective(Directive):
         elif 'doc' in self.options:
             cmd += ['-function', str(self.options.get('doc'))]
         elif 'functions' in self.options:
-            for f in str(self.options.get('functions')).split():
-                cmd += ['-function', f]
+            functions = self.options.get('functions').split()
+            if functions:
+                for f in functions:
+                    cmd += ['-function', f]
+            else:
+                cmd += ['-no-doc-sections']
 
         for pattern in export_file_patterns:
             for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters

[Matthew Wilcox]

On Sat, Jun 30, 2018 at 12:05:10AM +0300, Mike Rapoport wrote:
> @@ -488,14 +488,19 @@ doc: *title*
>      .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
>         :doc: High Definition Audio over HDMI and Display Port
>  
> -functions: *function* *[...]*
> +functions: *[ function ...]*
>    Include documentation for each *function* in *source*.
> +  If no *function* if specified, the documentaion for all functions

"is specified".  "documentation".

> -  Example::
> +  Examples::
>  
>      .. kernel-doc:: lib/bitmap.c
>         :functions: bitmap_parselist bitmap_parselist_user
>  
> +    .. kernel-doc:: lib/idr.c
> +       :functions:

Is this the right syntax?  Should we rather have:

    .. kernel-doc:: lib/idr.c
       :functions: *

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters

[Mike Rapoport]

On Sat, Jun 30, 2018 at 04:21:56AM -0700, Matthew Wilcox wrote:
> On Sat, Jun 30, 2018 at 12:05:10AM +0300, Mike Rapoport wrote:
> > @@ -488,14 +488,19 @@ doc: *title*
> >      .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
> >         :doc: High Definition Audio over HDMI and Display Port
> >  
> > -functions: *function* *[...]*
> > +functions: *[ function ...]*
> >    Include documentation for each *function* in *source*.
> > +  If no *function* if specified, the documentaion for all functions
> 
> "is specified".  "documentation".
> 
> > -  Example::
> > +  Examples::
> >  
> >      .. kernel-doc:: lib/bitmap.c
> >         :functions: bitmap_parselist bitmap_parselist_user
> >  
> > +    .. kernel-doc:: lib/idr.c
> > +       :functions:
> 
> Is this the right syntax?  Should we rather have:
> 
>     .. kernel-doc:: lib/idr.c
>        :functions: *

IMHO :functions: with no parameters is simpler.
 

-- 
Sincerely yours,
Mike.

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters

[Jonathan Corbet]

On Sat, 30 Jun 2018 17:59:27 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:

> > 
> > Is this the right syntax?  Should we rather have:
> > 
> >     .. kernel-doc:: lib/idr.c
> >        :functions: *  
> 
> IMHO :functions: with no parameters is simpler.

What I would really like to have there, actually, is a regex match (or,
probably better, a shell-glob match).  It would be easy to add, I've just
never gotten around to it.  That would make the above syntax just work for
those who preferred it.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3 2/2] docs/idr: use empty "functions" directive

[Mike Rapoport]

to avoid duplication of DOC: sections in the middle of the API reference.

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: Matthew Wilcox <willy@infradead.org>
---
 Documentation/core-api/idr.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/core-api/idr.rst b/Documentation/core-api/idr.rst
index 9078a5c..d351e88 100644
--- a/Documentation/core-api/idr.rst
+++ b/Documentation/core-api/idr.rst
@@ -76,4 +76,6 @@ Functions and structures
 ========================
 
 .. kernel-doc:: include/linux/idr.h
+   :functions:
 .. kernel-doc:: lib/idr.c
+   :functions:
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive

[Jonathan Corbet]

On Sat, 30 Jun 2018 00:05:09 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:

> These patches allow passing "-no-doc-sections" option to scripts/kernel-doc
> from the sphinx generator.
> 
> This allows to avoid duplicated DOC: sections when "kernel-doc:" directive
> is used without explicit selection of functions or function types. For
> instance, [1] has "IDA description" and "idr synchronization" twice.
> 
> v3 changes:
> * add description for empty "functions" directive to
> Documentation/doc-guide/kernel-doc.rst

Actually, I applied the previous set this morning...any chance you could
send me the docs update separately?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive

[Jonathan Corbet]

On Fri, 29 Jun 2018 15:07:34 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> > These patches allow passing "-no-doc-sections" option to scripts/kernel-doc
> > from the sphinx generator.
> > 
> > This allows to avoid duplicated DOC: sections when "kernel-doc:" directive
> > is used without explicit selection of functions or function types. For
> > instance, [1] has "IDA description" and "idr synchronization" twice.
> > 
> > v3 changes:
> > * add description for empty "functions" directive to
> > Documentation/doc-guide/kernel-doc.rst  
> 
> Actually, I applied the previous set this morning...any chance you could
> send me the docs update separately?

Never mind...I realized I hadn't pushed that work, so I just switched over
to the newer version, sorry for the noise.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html