[PATCH 2/2] docs/idr: use "nodocs" directive
to avoid duplication of DOC: sections in the middle of the API reference. Signed-off-by: Mike Rapoport --- 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..15eadf8 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 + :nodocs: .. kernel-doc:: lib/idr.c + :nodocs: -- 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 0/2] Documentation/sphinx: add "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. [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html Mike Rapoport (2): Documentation/sphinx: add "nodocs" directive docs/idr: use "nodocs" directive Documentation/core-api/idr.rst| 2 ++ Documentation/sphinx/kerneldoc.py | 3 +++ 2 files changed, 5 insertions(+) -- 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 1/2] Documentation/sphinx: add "nodocs" directive
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
---
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
--
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
Re: [PATCH 0/2] Documentation/sphinx: add "nodocs" directive
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 -- 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
Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive
On Mon, 18 Jun 2018, Mike Rapoport wrote:
> 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
> ---
> 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,
I'm not convinved this is the prettiest way to achieve what you
want. 'nodocs' seems kind of clunky.
I'd suggest supporting 'functions' without option arguments, and turning
that into kernel-doc -no-doc-sections.
The usage in patch 2/2 would turn into:
.. kernel-doc:: include/linux/idr.h
:functions:
which I think is much better overall in the rst source, complementing
the places where you use :doc:.
BR,
Jani.
> }
> 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):
--
Jani Nikula, Intel Open Source Graphics Center
--
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
Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive
On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote:
> On Mon, 18 Jun 2018, Mike Rapoport wrote:
> > 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
> > ---
> > 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,
>
> I'm not convinved this is the prettiest way to achieve what you
> want. 'nodocs' seems kind of clunky.
>
> I'd suggest supporting 'functions' without option arguments, and turning
> that into kernel-doc -no-doc-sections.
Do you mean something like this:
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):
> The usage in patch 2/2 would turn into:
>
> .. kernel-doc:: include/linux/idr.h
>:functions:
>
> which I think is much better overall in the rst source, complementing
> the places where you use :doc:.
>
> BR,
> Jani.
>
> > }
> > 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):
>
> --
> Jani Nikula, Intel Open Source Graphics Center
>
--
Sincerely yours,
Mike.
--
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
