On Tue, 19 Jun 2018, Mike Rapoport [off-list ref] wrote:

On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote:

quoted

On Tue, 19 Jun 2018, Mike Rapoport [off-list ref] wrote:

quoted

On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:

quoted

On Mon, 18 Jun 2018, Mike Rapoport [off-list ref] wrote:

quoted

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

quoted

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.

quoted

BR,
Jani.

quoted

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

quoted

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.

quoted

     }
     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