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@xxxxxxxxxxxxx>
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@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
