Re: [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive
On Sat, 30 Jun 2018 00:05:09 +0300 Mike Rapoport wrote: > 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. > > v3 changes: > * add description for empty "functions" directive to > Documentation/doc-guide/kernel-doc.rst Actually, I applied the previous set this morning...any chance you could send me the docs update separately? Thanks, jon -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive
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. v3 changes: * add description for empty "functions" directive to Documentation/doc-guide/kernel-doc.rst 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/doc-guide/kernel-doc.rst | 9 +++-- Documentation/sphinx/kerneldoc.py | 10 +++--- 3 files changed, 16 insertions(+), 5 deletions(-) -- 2.7.4 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
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
Acked-by: Matthew Wilcox
---
Documentation/doc-guide/kernel-doc.rst | 9 +++--
Documentation/sphinx/kerneldoc.py | 10 +++---
2 files changed, 14 insertions(+), 5 deletions(-)
diff --git a/Documentation/doc-guide/kernel-doc.rst
b/Documentation/doc-guide/kernel-doc.rst
index 80383b1..8db53cd 100644
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -488,14 +488,19 @@ doc: *title*
.. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
:doc: High Definition Audio over HDMI and Display Port
-functions: *function* *[...]*
+functions: *[ function ...]*
Include documentation for each *function* in *source*.
+ If no *function* if specified, the documentaion for all functions
+ and types in the *source* will be included.
- Example::
+ Examples::
.. kernel-doc:: lib/bitmap.c
:functions: bitmap_parselist bitmap_parselist_user
+.. kernel-doc:: lib/idr.c
+ :functions:
+
Without options, the kernel-doc directive includes all documentation comments
from the source file.
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 majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 2/2] docs/idr: use empty "functions" directive
to avoid duplication of DOC: sections in the middle of the API reference. Signed-off-by: Mike Rapoport Acked-by: Matthew Wilcox --- 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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
