* [PATCH 0/2] Documentation/sphinx: add "nodocs" directive
@ 2018-06-18 13:36 Mike Rapoport
2018-06-18 13:36 ` [PATCH 1/2] " Mike Rapoport
` (2 more replies)
0 siblings, 3 replies; 12+ messages in thread
From: Mike Rapoport @ 2018-06-18 13:36 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.
[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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
^ permalink raw reply [flat|nested] 12+ messages in thread* [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-18 13:36 [PATCH 0/2] Documentation/sphinx: add "nodocs" directive Mike Rapoport @ 2018-06-18 13:36 ` Mike Rapoport 2018-06-18 20:01 ` Jani Nikula 2018-06-18 13:36 ` [PATCH 2/2] docs/idr: use " Mike Rapoport 2018-06-18 17:10 ` [PATCH 0/2] Documentation/sphinx: add " Matthew Wilcox 2 siblings, 1 reply; 12+ messages in thread From: Mike Rapoport @ 2018-06-18 13:36 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 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 <rppt@linux.vnet.ibm.com> --- 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-18 13:36 ` [PATCH 1/2] " Mike Rapoport @ 2018-06-18 20:01 ` Jani Nikula 2018-06-19 5:03 ` Mike Rapoport 0 siblings, 1 reply; 12+ messages in thread From: Jani Nikula @ 2018-06-18 20:01 UTC (permalink / raw) To: Mike Rapoport, Jonathan Corbet; +Cc: Matthew Wilcox, linux-doc, Mike Rapoport On Mon, 18 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> 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 <rppt@linux.vnet.ibm.com> > --- > 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-18 20:01 ` Jani Nikula @ 2018-06-19 5:03 ` Mike Rapoport 2018-06-19 7:29 ` Jani Nikula 0 siblings, 1 reply; 12+ messages in thread From: Mike Rapoport @ 2018-06-19 5:03 UTC (permalink / raw) To: Jani Nikula; +Cc: Jonathan Corbet, Matthew Wilcox, linux-doc On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote: > On Mon, 18 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> 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 <rppt@linux.vnet.ibm.com> > > --- > > 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-19 5:03 ` Mike Rapoport @ 2018-06-19 7:29 ` Jani Nikula 2018-06-19 7:50 ` Mike Rapoport 0 siblings, 1 reply; 12+ messages in thread From: Jani Nikula @ 2018-06-19 7:29 UTC (permalink / raw) To: Mike Rapoport; +Cc: Jonathan Corbet, Matthew Wilcox, linux-doc On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote: > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote: >> On Mon, 18 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> 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 <rppt@linux.vnet.ibm.com> >> > --- >> > 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: Yes. > > 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() Does .split() get upset if there's no argument? Or do you get an empty string if there are no options? I forget. BR, Jani. > + 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 >> -- 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-19 7:29 ` Jani Nikula @ 2018-06-19 7:50 ` Mike Rapoport 2018-06-19 8:09 ` Jani Nikula 0 siblings, 1 reply; 12+ messages in thread From: Mike Rapoport @ 2018-06-19 7:50 UTC (permalink / raw) To: Jani Nikula; +Cc: Jonathan Corbet, Matthew Wilcox, linux-doc On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote: > On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote: > > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote: > >> On Mon, 18 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> 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 <rppt@linux.vnet.ibm.com> > >> > --- > >> > 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: > > Yes. > > > > > 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() > > Does .split() get upset if there's no argument? Or do you get an empty > string if there are no options? I forget. "".split() gives an empty list. > BR, > Jani. > > > + 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 > >> > > -- > 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-19 7:50 ` Mike Rapoport @ 2018-06-19 8:09 ` Jani Nikula 2018-06-19 13:09 ` Mike Rapoport 0 siblings, 1 reply; 12+ messages in thread From: Jani Nikula @ 2018-06-19 8:09 UTC (permalink / raw) To: Mike Rapoport; +Cc: Jonathan Corbet, Matthew Wilcox, linux-doc On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote: > On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote: >> On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote: >> > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote: >> >> On Mon, 18 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> 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 <rppt@linux.vnet.ibm.com> >> >> > --- >> >> > 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: >> >> Yes. >> >> > >> > 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() >> >> Does .split() get upset if there's no argument? Or do you get an empty >> string if there are no options? I forget. > > "".split() gives an empty list. I tried to say, does self.options.get('functions') return an empty string or None if there are no options? BR, Jani. > >> BR, >> Jani. >> >> > + 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 >> >> >> >> -- >> Jani Nikula, Intel Open Source Graphics Center >> -- 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 1/2] Documentation/sphinx: add "nodocs" directive 2018-06-19 8:09 ` Jani Nikula @ 2018-06-19 13:09 ` Mike Rapoport 0 siblings, 0 replies; 12+ messages in thread From: Mike Rapoport @ 2018-06-19 13:09 UTC (permalink / raw) To: Jani Nikula; +Cc: Jonathan Corbet, Matthew Wilcox, linux-doc On Tue, Jun 19, 2018 at 11:09:42AM +0300, Jani Nikula wrote: > On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote: > > On Tue, Jun 19, 2018 at 10:29:20AM +0300, Jani Nikula wrote: > >> On Tue, 19 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> wrote: > >> > On Mon, Jun 18, 2018 at 11:01:32PM +0300, Jani Nikula wrote: > >> >> On Mon, 18 Jun 2018, Mike Rapoport <rppt@linux.vnet.ibm.com> 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 <rppt@linux.vnet.ibm.com> > >> >> > --- > >> >> > 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: > >> > >> Yes. > >> > >> > > >> > 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() > >> > >> Does .split() get upset if there's no argument? Or do you get an empty > >> string if there are no options? I forget. > > > > "".split() gives an empty list. > > I tried to say, does self.options.get('functions') return an empty > string or None if there are no options? It returns an empty string. > BR, > Jani. > > > > > >> BR, > >> Jani. > >> > >> > + 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 > >> >> > >> > >> -- > >> Jani Nikula, Intel Open Source Graphics Center > >> > > -- > 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 2/2] docs/idr: use "nodocs" directive 2018-06-18 13:36 [PATCH 0/2] Documentation/sphinx: add "nodocs" directive Mike Rapoport 2018-06-18 13:36 ` [PATCH 1/2] " Mike Rapoport @ 2018-06-18 13:36 ` Mike Rapoport 2018-06-18 17:10 ` [PATCH 0/2] Documentation/sphinx: add " Matthew Wilcox 2 siblings, 0 replies; 12+ messages in thread From: Mike Rapoport @ 2018-06-18 13:36 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> --- 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 majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: [PATCH 0/2] Documentation/sphinx: add "nodocs" directive 2018-06-18 13:36 [PATCH 0/2] Documentation/sphinx: add "nodocs" directive Mike Rapoport 2018-06-18 13:36 ` [PATCH 1/2] " Mike Rapoport 2018-06-18 13:36 ` [PATCH 2/2] docs/idr: use " Mike Rapoport @ 2018-06-18 17:10 ` Matthew Wilcox 2018-06-19 14:11 ` Matthew Wilcox 2 siblings, 1 reply; 12+ messages in thread From: Matthew Wilcox @ 2018-06-18 17:10 UTC (permalink / raw) To: Mike Rapoport; +Cc: Jonathan Corbet, Matthew Wilcox, Jani Nikula, linux-doc 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> -- 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] 12+ messages in thread
* Re: [PATCH 0/2] Documentation/sphinx: add "nodocs" directive 2018-06-18 17:10 ` [PATCH 0/2] Documentation/sphinx: add " Matthew Wilcox @ 2018-06-19 14:11 ` Matthew Wilcox 2018-06-19 14:49 ` Mike Rapoport 0 siblings, 1 reply; 12+ messages in thread From: Matthew Wilcox @ 2018-06-19 14:11 UTC (permalink / raw) To: Mike Rapoport; +Cc: Jonathan Corbet, Matthew Wilcox, Jani Nikula, linux-doc 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. -- 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] 12+ messages in thread
* Re: [PATCH 0/2] Documentation/sphinx: add "nodocs" directive 2018-06-19 14:11 ` Matthew Wilcox @ 2018-06-19 14:49 ` Mike Rapoport 0 siblings, 0 replies; 12+ messages in thread From: Mike Rapoport @ 2018-06-19 14:49 UTC (permalink / raw) To: Matthew Wilcox; +Cc: Jonathan Corbet, Matthew Wilcox, Jani Nikula, linux-doc 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 ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2018-06-19 14:49 UTC | newest] Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2018-06-18 13:36 [PATCH 0/2] Documentation/sphinx: add "nodocs" directive Mike Rapoport 2018-06-18 13:36 ` [PATCH 1/2] " Mike Rapoport 2018-06-18 20:01 ` Jani Nikula 2018-06-19 5:03 ` Mike Rapoport 2018-06-19 7:29 ` Jani Nikula 2018-06-19 7:50 ` Mike Rapoport 2018-06-19 8:09 ` Jani Nikula 2018-06-19 13:09 ` Mike Rapoport 2018-06-18 13:36 ` [PATCH 2/2] docs/idr: use " Mike Rapoport 2018-06-18 17:10 ` [PATCH 0/2] Documentation/sphinx: add " Matthew Wilcox 2018-06-19 14:11 ` Matthew Wilcox 2018-06-19 14:49 ` Mike Rapoport
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.