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

Mike Rapoport
2018-06-18T13:36:52Z

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