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

[PATCH v2 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.

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/sphinx/kerneldoc.py | 10 +++++++---
 2 files changed, 9 insertions(+), 3 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 v2 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/sphinx/kerneldoc.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

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

[PATCH v2 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 v2 1/2] Documentation/sphinx: allow "functions" with no parameters

[Jani Nikula]

On Wed, 20 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> 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>

Looks good to me. Though I do realize now that I overlooked that this
applies to not only functions, but also to other non-DOC documentation
comments. I guess up to Jon to decide.

Please do give the cobbler's children some shoes, and document this in
Documentation/doc-guide/kernel-doc.rst.

Thanks,
Jani.

> ---
>  Documentation/sphinx/kerneldoc.py | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> 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):

-- 
Jani Nikula, Intel Open Source Graphics Center
--
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 v2 1/2] Documentation/sphinx: allow "functions" with no parameters

[Mike Rapoport]

On Wed, Jun 20, 2018 at 10:19:36AM +0300, Jani Nikula wrote:
> On Wed, 20 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> > 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>
> 
> Looks good to me. Though I do realize now that I overlooked that this
> applies to not only functions, but also to other non-DOC documentation
> comments. I guess up to Jon to decide.
 
We can name it "everything-except-doc-sections" ;-)

> Please do give the cobbler's children some shoes, and document this in
> Documentation/doc-guide/kernel-doc.rst.

Sure. I'd just wait until there's consensus on the name :)

> Thanks,
> Jani.
> 
> > ---
> >  Documentation/sphinx/kerneldoc.py | 10 +++++++---
> >  1 file changed, 7 insertions(+), 3 deletions(-)
> >
> > 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):
> 
> -- 
> Jani Nikula, Intel Open Source Graphics Center
> 

-- 
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 v2 1/2] Documentation/sphinx: allow "functions" with no parameters

[Jonathan Corbet]

On Wed, 20 Jun 2018 11:49:12 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:

> > Looks good to me. Though I do realize now that I overlooked that this
> > applies to not only functions, but also to other non-DOC documentation
> > comments. I guess up to Jon to decide.  
>  
> We can name it "everything-except-doc-sections" ;-)

I suppose it could be :code: or :declarations: or some such.  But I think
I'm inclined to just apply the patches as they are.  The handling of
structs and such has always been a bit bolted onto the side, this doesn't
really change anything.

(Sorry for my absence in general - took some much-needed offline time).

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