* [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive
@ 2018-06-29 21:05 Mike Rapoport
2018-06-29 21:05 ` [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters Mike Rapoport
` (2 more replies)
0 siblings, 3 replies; 8+ messages in thread
From: Mike Rapoport @ 2018-06-29 21:05 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Matthew Wilcox, Jani Nikula, linux-doc, Mike Rapoport
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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
2018-06-29 21:05 [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Mike Rapoport
@ 2018-06-29 21:05 ` Mike Rapoport
2018-06-30 11:21 ` Matthew Wilcox
2018-06-29 21:05 ` [PATCH v3 2/2] docs/idr: use empty "functions" directive Mike Rapoport
2018-06-29 21:07 ` [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Jonathan Corbet
2 siblings, 1 reply; 8+ messages in thread
From: Mike Rapoport @ 2018-06-29 21:05 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Matthew Wilcox, Jani Nikula, linux-doc, Mike Rapoport
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 <rppt@linux.vnet.ibm.com>
Acked-by: Matthew Wilcox <willy@infradead.org>
---
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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH v3 2/2] docs/idr: use empty "functions" directive
2018-06-29 21:05 [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Mike Rapoport
2018-06-29 21:05 ` [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters Mike Rapoport
@ 2018-06-29 21:05 ` Mike Rapoport
2018-06-29 21:07 ` [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Jonathan Corbet
2 siblings, 0 replies; 8+ messages in thread
From: Mike Rapoport @ 2018-06-29 21:05 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Matthew Wilcox, Jani Nikula, linux-doc, Mike Rapoport
to avoid duplication of DOC: sections in the middle of the API reference.
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: Matthew Wilcox <willy@infradead.org>
---
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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive
2018-06-29 21:05 [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Mike Rapoport
2018-06-29 21:05 ` [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters Mike Rapoport
2018-06-29 21:05 ` [PATCH v3 2/2] docs/idr: use empty "functions" directive Mike Rapoport
@ 2018-06-29 21:07 ` Jonathan Corbet
2018-06-30 13:56 ` Jonathan Corbet
2 siblings, 1 reply; 8+ messages in thread
From: Jonathan Corbet @ 2018-06-29 21:07 UTC (permalink / raw)
To: Mike Rapoport; +Cc: Matthew Wilcox, Jani Nikula, linux-doc
On Sat, 30 Jun 2018 00:05:09 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> 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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
2018-06-29 21:05 ` [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters Mike Rapoport
@ 2018-06-30 11:21 ` Matthew Wilcox
2018-06-30 14:59 ` Mike Rapoport
0 siblings, 1 reply; 8+ messages in thread
From: Matthew Wilcox @ 2018-06-30 11:21 UTC (permalink / raw)
To: Mike Rapoport; +Cc: Jonathan Corbet, Jani Nikula, linux-doc
On Sat, Jun 30, 2018 at 12:05:10AM +0300, Mike Rapoport wrote:
> @@ -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
"is specified". "documentation".
> - Example::
> + Examples::
>
> .. kernel-doc:: lib/bitmap.c
> :functions: bitmap_parselist bitmap_parselist_user
>
> + .. kernel-doc:: lib/idr.c
> + :functions:
Is this the right syntax? Should we rather have:
.. kernel-doc:: lib/idr.c
:functions: *
--
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive
2018-06-29 21:07 ` [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Jonathan Corbet
@ 2018-06-30 13:56 ` Jonathan Corbet
0 siblings, 0 replies; 8+ messages in thread
From: Jonathan Corbet @ 2018-06-30 13:56 UTC (permalink / raw)
To: Mike Rapoport; +Cc: Matthew Wilcox, Jani Nikula, linux-doc
On Fri, 29 Jun 2018 15:07:34 -0600
Jonathan Corbet <corbet@lwn.net> 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?
Never mind...I realized I hadn't pushed that work, so I just switched over
to the newer version, sorry for the noise.
jon
--
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
2018-06-30 11:21 ` Matthew Wilcox
@ 2018-06-30 14:59 ` Mike Rapoport
2018-06-30 15:33 ` Jonathan Corbet
0 siblings, 1 reply; 8+ messages in thread
From: Mike Rapoport @ 2018-06-30 14:59 UTC (permalink / raw)
To: Matthew Wilcox; +Cc: Jonathan Corbet, Jani Nikula, linux-doc
On Sat, Jun 30, 2018 at 04:21:56AM -0700, Matthew Wilcox wrote:
> On Sat, Jun 30, 2018 at 12:05:10AM +0300, Mike Rapoport wrote:
> > @@ -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
>
> "is specified". "documentation".
>
> > - Example::
> > + Examples::
> >
> > .. kernel-doc:: lib/bitmap.c
> > :functions: bitmap_parselist bitmap_parselist_user
> >
> > + .. kernel-doc:: lib/idr.c
> > + :functions:
>
> Is this the right syntax? Should we rather have:
>
> .. kernel-doc:: lib/idr.c
> :functions: *
IMHO :functions: with no parameters is simpler.
--
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
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters
2018-06-30 14:59 ` Mike Rapoport
@ 2018-06-30 15:33 ` Jonathan Corbet
0 siblings, 0 replies; 8+ messages in thread
From: Jonathan Corbet @ 2018-06-30 15:33 UTC (permalink / raw)
To: Mike Rapoport; +Cc: Matthew Wilcox, Jani Nikula, linux-doc
On Sat, 30 Jun 2018 17:59:27 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> >
> > Is this the right syntax? Should we rather have:
> >
> > .. kernel-doc:: lib/idr.c
> > :functions: *
>
> IMHO :functions: with no parameters is simpler.
What I would really like to have there, actually, is a regex match (or,
probably better, a shell-glob match). It would be easy to add, I've just
never gotten around to it. That would make the above syntax just work for
those who preferred it.
jon
--
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
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2018-06-30 15:33 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-06-29 21:05 [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Mike Rapoport
2018-06-29 21:05 ` [PATCH v3 1/2] Documentation/sphinx: allow "functions" with no parameters Mike Rapoport
2018-06-30 11:21 ` Matthew Wilcox
2018-06-30 14:59 ` Mike Rapoport
2018-06-30 15:33 ` Jonathan Corbet
2018-06-29 21:05 ` [PATCH v3 2/2] docs/idr: use empty "functions" directive Mike Rapoport
2018-06-29 21:07 ` [PATCH v3 0/2] Documentation/sphinx: add kind of "nodocs" directive Jonathan Corbet
2018-06-30 13:56 ` Jonathan Corbet
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.