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

[Mike Rapoport <rppt@linux.vnet.ibm.com>]

On Tue, Jun 19, 2018 at 07:11:56AM -0700, Matthew Wilcox wrote:
> 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@infradead.org>
> 
> 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.
> 

Actually, in the IDR case the same trick would work.

In more general case it's even possible to use

.. kernel-doc:: path/to/file.c
   :export:

.. kernel-doc: path/to/file.c
   :internal:

and get all the functions without the docs sections :)

But IMHO having a directive for this would be nicer. If there are no
objections to Jani's  suggestion to use empty :functions: instead of
:nodoc: I'm going to send v2.

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