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

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:

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.

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

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