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

[PATCH 0/2] Documentation/sphinx: add "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.

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

Mike Rapoport (2):
  Documentation/sphinx: add "nodocs" directive
  docs/idr: use "nodocs" directive

 Documentation/core-api/idr.rst    | 2 ++
 Documentation/sphinx/kerneldoc.py | 3 +++
 2 files changed, 5 insertions(+)

-- 
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 1/2] Documentation/sphinx: add "nodocs" directive

[Mike Rapoport]

When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was explictly
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.

Addition of "nodocs" directive prevents the duplication without the need to
explicitly define what functions should be include in the API reference.

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

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
---
 Documentation/sphinx/kerneldoc.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index fbedcc3..bc5dd05 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
         'functions': directives.unchanged_required,
         'export': directives.unchanged,
         'internal': directives.unchanged,
+        'nodocs': directives.unchanged,
     }
     has_content = False
 
@@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
         elif 'functions' in self.options:
             for f in str(self.options.get('functions')).split():
                 cmd += ['-function', f]
+        elif 'nodocs' in self.options:
+            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 2/2] docs/idr: use "nodocs" 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>
---
 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..15eadf8 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
+   :nodocs:
 .. kernel-doc:: lib/idr.c
+   :nodocs:
-- 
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 0/2] Documentation/sphinx: add "nodocs" directive

[Matthew Wilcox]

On Mon, Jun 18, 2018 at 04:36:34PM +0300, Mike Rapoport wrote:
> 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.

Hah, I just found an abandoned patch for this in a disused git tree.
I was wondering whether I needed to resurrect it.  Enthusiastically,

Acked-by: Matthew Wilcox <willy@infradead.org>
--
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 1/2] Documentation/sphinx: add "nodocs" directive

[Jani Nikula]

On Mon, 18 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 explictly
> 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.
>
> Addition of "nodocs" directive prevents the duplication without the need to
> explicitly define what functions should be include in the API reference.
>
> [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>
> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> ---
>  Documentation/sphinx/kerneldoc.py | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index fbedcc3..bc5dd05 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
>          'functions': directives.unchanged_required,
>          'export': directives.unchanged,
>          'internal': directives.unchanged,
> +        'nodocs': directives.unchanged,

I'm not convinved this is the prettiest way to achieve what you
want. 'nodocs' seems kind of clunky.

I'd suggest supporting 'functions' without option arguments, and turning
that into kernel-doc -no-doc-sections.

The usage in patch 2/2 would turn into:

.. kernel-doc:: include/linux/idr.h
   :functions:

which I think is much better overall in the rst source, complementing
the places where you use :doc:.

BR,
Jani.

>      }
>      has_content = False
>  
> @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
>          elif 'functions' in self.options:
>              for f in str(self.options.get('functions')).split():
>                  cmd += ['-function', f]
> +        elif 'nodocs' in self.options:
> +            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 1/2] Documentation/sphinx: add "nodocs" directive

[Mike Rapoport]

On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
> On Mon, 18 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 explictly
> > 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.
> >
> > Addition of "nodocs" directive prevents the duplication without the need to
> > explicitly define what functions should be include in the API reference.
> >
> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
> >
> > Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> > ---
> >  Documentation/sphinx/kerneldoc.py | 3 +++
> >  1 file changed, 3 insertions(+)
> >
> > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> > index fbedcc3..bc5dd05 100644
> > --- a/Documentation/sphinx/kerneldoc.py
> > +++ b/Documentation/sphinx/kerneldoc.py
> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
> >          'functions': directives.unchanged_required,
> >          'export': directives.unchanged,
> >          'internal': directives.unchanged,
> > +        'nodocs': directives.unchanged,
> 
> I'm not convinved this is the prettiest way to achieve what you
> want. 'nodocs' seems kind of clunky.
> 
> I'd suggest supporting 'functions' without option arguments, and turning
> that into kernel-doc -no-doc-sections.

Do you mean something like this:

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):

> The usage in patch 2/2 would turn into:
> 
> .. kernel-doc:: include/linux/idr.h
>    :functions:
> 
> which I think is much better overall in the rst source, complementing
> the places where you use :doc:.
> 
> BR,
> Jani.
> 
> >      }
> >      has_content = False
> >  
> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
> >          elif 'functions' in self.options:
> >              for f in str(self.options.get('functions')).split():
> >                  cmd += ['-function', f]
> > +        elif 'nodocs' in self.options:
> > +            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 1/2] Documentation/sphinx: add "nodocs" directive

[Jani Nikula]

On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
>> On Mon, 18 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 explictly
>> > 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.
>> >
>> > Addition of "nodocs" directive prevents the duplication without the need to
>> > explicitly define what functions should be include in the API reference.
>> >
>> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>> >
>> > Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
>> > ---
>> >  Documentation/sphinx/kerneldoc.py | 3 +++
>> >  1 file changed, 3 insertions(+)
>> >
>> > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
>> > index fbedcc3..bc5dd05 100644
>> > --- a/Documentation/sphinx/kerneldoc.py
>> > +++ b/Documentation/sphinx/kerneldoc.py
>> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
>> >          'functions': directives.unchanged_required,
>> >          'export': directives.unchanged,
>> >          'internal': directives.unchanged,
>> > +        'nodocs': directives.unchanged,
>> 
>> I'm not convinved this is the prettiest way to achieve what you
>> want. 'nodocs' seems kind of clunky.
>> 
>> I'd suggest supporting 'functions' without option arguments, and turning
>> that into kernel-doc -no-doc-sections.
>
> Do you mean something like this:

Yes.

>
> 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()

Does .split() get upset if there's no argument? Or do you get an empty
string if there are no options? I forget.

BR,
Jani.

> +            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):
>
>> The usage in patch 2/2 would turn into:
>> 
>> .. kernel-doc:: include/linux/idr.h
>>    :functions:
>> 
>> which I think is much better overall in the rst source, complementing
>> the places where you use :doc:.
>> 
>> BR,
>> Jani.
>> 
>> >      }
>> >      has_content = False
>> >  
>> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
>> >          elif 'functions' in self.options:
>> >              for f in str(self.options.get('functions')).split():
>> >                  cmd += ['-function', f]
>> > +        elif 'nodocs' in self.options:
>> > +            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
>> 

-- 
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 1/2] Documentation/sphinx: add "nodocs" directive

[Mike Rapoport]

On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote:
> On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
> >> On Mon, 18 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 explictly
> >> > 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.
> >> >
> >> > Addition of "nodocs" directive prevents the duplication without the need to
> >> > explicitly define what functions should be include in the API reference.
> >> >
> >> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
> >> >
> >> > Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> >> > ---
> >> >  Documentation/sphinx/kerneldoc.py | 3 +++
> >> >  1 file changed, 3 insertions(+)
> >> >
> >> > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> >> > index fbedcc3..bc5dd05 100644
> >> > --- a/Documentation/sphinx/kerneldoc.py
> >> > +++ b/Documentation/sphinx/kerneldoc.py
> >> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
> >> >          'functions': directives.unchanged_required,
> >> >          'export': directives.unchanged,
> >> >          'internal': directives.unchanged,
> >> > +        'nodocs': directives.unchanged,
> >> 
> >> I'm not convinved this is the prettiest way to achieve what you
> >> want. 'nodocs' seems kind of clunky.
> >> 
> >> I'd suggest supporting 'functions' without option arguments, and turning
> >> that into kernel-doc -no-doc-sections.
> >
> > Do you mean something like this:
> 
> Yes.
> 
> >
> > 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()
> 
> Does .split() get upset if there's no argument? Or do you get an empty
> string if there are no options? I forget.

"".split() gives an empty list.
 
> BR,
> Jani.
> 
> > +            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):
> >
> >> The usage in patch 2/2 would turn into:
> >> 
> >> .. kernel-doc:: include/linux/idr.h
> >>    :functions:
> >> 
> >> which I think is much better overall in the rst source, complementing
> >> the places where you use :doc:.
> >> 
> >> BR,
> >> Jani.
> >> 
> >> >      }
> >> >      has_content = False
> >> >  
> >> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
> >> >          elif 'functions' in self.options:
> >> >              for f in str(self.options.get('functions')).split():
> >> >                  cmd += ['-function', f]
> >> > +        elif 'nodocs' in self.options:
> >> > +            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
> >> 
> 
> -- 
> 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 1/2] Documentation/sphinx: add "nodocs" directive

[Jani Nikula]

On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote:
>> On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
>> > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
>> >> On Mon, 18 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 explictly
>> >> > 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.
>> >> >
>> >> > Addition of "nodocs" directive prevents the duplication without the need to
>> >> > explicitly define what functions should be include in the API reference.
>> >> >
>> >> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
>> >> >
>> >> > Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
>> >> > ---
>> >> >  Documentation/sphinx/kerneldoc.py | 3 +++
>> >> >  1 file changed, 3 insertions(+)
>> >> >
>> >> > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
>> >> > index fbedcc3..bc5dd05 100644
>> >> > --- a/Documentation/sphinx/kerneldoc.py
>> >> > +++ b/Documentation/sphinx/kerneldoc.py
>> >> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
>> >> >          'functions': directives.unchanged_required,
>> >> >          'export': directives.unchanged,
>> >> >          'internal': directives.unchanged,
>> >> > +        'nodocs': directives.unchanged,
>> >> 
>> >> I'm not convinved this is the prettiest way to achieve what you
>> >> want. 'nodocs' seems kind of clunky.
>> >> 
>> >> I'd suggest supporting 'functions' without option arguments, and turning
>> >> that into kernel-doc -no-doc-sections.
>> >
>> > Do you mean something like this:
>> 
>> Yes.
>> 
>> >
>> > 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()
>> 
>> Does .split() get upset if there's no argument? Or do you get an empty
>> string if there are no options? I forget.
>
> "".split() gives an empty list.

I tried to say, does self.options.get('functions') return an empty
string or None if there are no options?

BR,
Jani.


>  
>> BR,
>> Jani.
>> 
>> > +            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):
>> >
>> >> The usage in patch 2/2 would turn into:
>> >> 
>> >> .. kernel-doc:: include/linux/idr.h
>> >>    :functions:
>> >> 
>> >> which I think is much better overall in the rst source, complementing
>> >> the places where you use :doc:.
>> >> 
>> >> BR,
>> >> Jani.
>> >> 
>> >> >      }
>> >> >      has_content = False
>> >> >  
>> >> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
>> >> >          elif 'functions' in self.options:
>> >> >              for f in str(self.options.get('functions')).split():
>> >> >                  cmd += ['-function', f]
>> >> > +        elif 'nodocs' in self.options:
>> >> > +            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
>> >> 
>> 
>> -- 
>> Jani Nikula, Intel Open Source Graphics Center
>> 

-- 
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 1/2] Documentation/sphinx: add "nodocs" directive

[Mike Rapoport]

On Tue, Jun 19, 2018 at 11:09:42AM +0300, Jani Nikula wrote:
> On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> > On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote:
> >> On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> >> > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
> >> >> On Mon, 18 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 explictly
> >> >> > 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.
> >> >> >
> >> >> > Addition of "nodocs" directive prevents the duplication without the need to
> >> >> > explicitly define what functions should be include in the API reference.
> >> >> >
> >> >> > [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
> >> >> >
> >> >> > Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> >> >> > ---
> >> >> >  Documentation/sphinx/kerneldoc.py | 3 +++
> >> >> >  1 file changed, 3 insertions(+)
> >> >> >
> >> >> > diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> >> >> > index fbedcc3..bc5dd05 100644
> >> >> > --- a/Documentation/sphinx/kerneldoc.py
> >> >> > +++ b/Documentation/sphinx/kerneldoc.py
> >> >> > @@ -50,6 +50,7 @@ class KernelDocDirective(Directive):
> >> >> >          'functions': directives.unchanged_required,
> >> >> >          'export': directives.unchanged,
> >> >> >          'internal': directives.unchanged,
> >> >> > +        'nodocs': directives.unchanged,
> >> >> 
> >> >> I'm not convinved this is the prettiest way to achieve what you
> >> >> want. 'nodocs' seems kind of clunky.
> >> >> 
> >> >> I'd suggest supporting 'functions' without option arguments, and turning
> >> >> that into kernel-doc -no-doc-sections.
> >> >
> >> > Do you mean something like this:
> >> 
> >> Yes.
> >> 
> >> >
> >> > 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()
> >> 
> >> Does .split() get upset if there's no argument? Or do you get an empty
> >> string if there are no options? I forget.
> >
> > "".split() gives an empty list.
> 
> I tried to say, does self.options.get('functions') return an empty
> string or None if there are no options?

It returns an empty string.
 
> BR,
> Jani.
> 
> 
> >  
> >> BR,
> >> Jani.
> >> 
> >> > +            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):
> >> >
> >> >> The usage in patch 2/2 would turn into:
> >> >> 
> >> >> .. kernel-doc:: include/linux/idr.h
> >> >>    :functions:
> >> >> 
> >> >> which I think is much better overall in the rst source, complementing
> >> >> the places where you use :doc:.
> >> >> 
> >> >> BR,
> >> >> Jani.
> >> >> 
> >> >> >      }
> >> >> >      has_content = False
> >> >> >  
> >> >> > @@ -77,6 +78,8 @@ class KernelDocDirective(Directive):
> >> >> >          elif 'functions' in self.options:
> >> >> >              for f in str(self.options.get('functions')).split():
> >> >> >                  cmd += ['-function', f]
> >> >> > +        elif 'nodocs' in self.options:
> >> >> > +            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
> >> >> 
> >> 
> >> -- 
> >> Jani Nikula, Intel Open Source Graphics Center
> >> 
> 
> -- 
> 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 0/2] Documentation/sphinx: add "nodocs" directive

[Matthew Wilcox]

On Mon, Jun 18, 2018 at 10:10:28AM -0700, Matthew Wilcox wrote:
> On Mon, Jun 18, 2018 at 04:36:34PM +0300, Mike Rapoport wrote:
> > 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.
> 
> Hah, I just found an abandoned patch for this in a disused git tree.
> I was wondering whether I needed to resurrect it.  Enthusiastically,
> 
> Acked-by: Matthew Wilcox <willy@infradead.org>

Here's the patch I found (I couldn't refind it at the time):

diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
index d15e07f36881..d86d88da1d75 100644
--- a/Documentation/sphinx/kerneldoc.py
+++ b/Documentation/sphinx/kerneldoc.py
@@ -47,6 +47,7 @@ class KernelDocDirective(Directive):
     optional_arguments = 4
     option_spec = {
         'doc': directives.unchanged_required,
+        'nodoc': directives.unchanged,
         'functions': directives.unchanged_required,
         'export': directives.unchanged,
         'internal': directives.unchanged,
@@ -74,6 +75,8 @@ class KernelDocDirective(Directive):
             export_file_patterns = str(self.options.get('internal')).split()
         elif 'doc' in self.options:
             cmd += ['-function', str(self.options.get('doc'))]
+        elif 'nodoc' in self.options:
+            cmd += ['-no-doc-sections']
         elif 'functions' in self.options:
             for f in str(self.options.get('functions')).split():
                 cmd += ['-function', f]

I did it while I was trying to create good radix tree documentation,
which led to me realising that was a Herculean task (specifically: the
stables).

I ended up doing this instead:

+The Public API
+==============
+
+The public API can be found in ``<linux/radix-tree.h>``.  To use a
+radix tree in your data structure, embed a :c:type:`struct radix_tree_root`
+in it, and initialise it using ``INIT_RADIX_TREE``.  You can also use
+a file-local or global radix tree by defining a :c:type:`RADIX_TREE` as you
+would a :c:type:`LIST_HEAD`.
+
+.. Not actually "internal", but I need to exclude the 'doc' paragraph, and
+   this is the best way to do it.
+.. kernel-doc:: include/linux/radix-tree.h
+   :internal:
+
+.. kernel-doc:: lib/radix-tree.c
+   :export:

I'm not sure if I agree with me-of-January-2017 that this is the "best"
way to do it, but maybe that'll point to another way of achieving the
same thing.
--
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 0/2] Documentation/sphinx: add "nodocs" directive

[Mike Rapoport]

On Tue, Jun 19, 2018 at 07:11:56AM -0700, Matthew Wilcox wrote:
> On Mon, Jun 18, 2018 at 10:10:28AM -0700, Matthew Wilcox wrote:
> > On Mon, Jun 18, 2018 at 04:36:34PM +0300, Mike Rapoport wrote:
> > > 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.
> > 
> > Hah, I just found an abandoned patch for this in a disused git tree.
> > I was wondering whether I needed to resurrect it.  Enthusiastically,
> > 
> > Acked-by: Matthew Wilcox <willy@infradead.org>
> 
> Here's the patch I found (I couldn't refind it at the time):
> 
> diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py
> index d15e07f36881..d86d88da1d75 100644
> --- a/Documentation/sphinx/kerneldoc.py
> +++ b/Documentation/sphinx/kerneldoc.py
> @@ -47,6 +47,7 @@ class KernelDocDirective(Directive):
>      optional_arguments = 4
>      option_spec = {
>          'doc': directives.unchanged_required,
> +        'nodoc': directives.unchanged,
>          'functions': directives.unchanged_required,
>          'export': directives.unchanged,
>          'internal': directives.unchanged,
> @@ -74,6 +75,8 @@ class KernelDocDirective(Directive):
>              export_file_patterns = str(self.options.get('internal')).split()
>          elif 'doc' in self.options:
>              cmd += ['-function', str(self.options.get('doc'))]
> +        elif 'nodoc' in self.options:
> +            cmd += ['-no-doc-sections']
>          elif 'functions' in self.options:
>              for f in str(self.options.get('functions')).split():
>                  cmd += ['-function', f]
> 
> I did it while I was trying to create good radix tree documentation,
> which led to me realising that was a Herculean task (specifically: the
> stables).
> 
> I ended up doing this instead:
> 
> +The Public API
> +==============
> +
> +The public API can be found in ``<linux/radix-tree.h>``.  To use a
> +radix tree in your data structure, embed a :c:type:`struct radix_tree_root`
> +in it, and initialise it using ``INIT_RADIX_TREE``.  You can also use
> +a file-local or global radix tree by defining a :c:type:`RADIX_TREE` as you
> +would a :c:type:`LIST_HEAD`.
> +
> +.. Not actually "internal", but I need to exclude the 'doc' paragraph, and
> +   this is the best way to do it.
> +.. kernel-doc:: include/linux/radix-tree.h
> +   :internal:
> +
> +.. kernel-doc:: lib/radix-tree.c
> +   :export:
> 
> I'm not sure if I agree with me-of-January-2017 that this is the "best"
> way to do it, but maybe that'll point to another way of achieving the
> same thing.
> 

Actually, in the IDR case the same trick would work.

In more general case it's even possible to use

.. kernel-doc:: path/to/file.c
   :export:

.. kernel-doc: path/to/file.c
   :internal:

and get all the functions without the docs sections :)

But IMHO having a directive for this would be nicer. If there are no
objections to Jani's  suggestion to use empty :functions: instead of
:nodoc: I'm going to send v2.

-- 
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