Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1429762 > unrolled thread

[docs-next PATCH v2 00/11] Documentation/sphinx follow-up, again

Back to article view | Back to linux.kernel

Contents

  [docs-next PATCH v2 00/11] Documentation/sphinx follow-up, again Jani Nikula <jani.nikula@intel.com> - 2016-06-23 14:30 +0200
    [docs-next PATCH v2 11/11] Documentation: add top level 'make help' output for Sphinx Jani Nikula <jani.nikula@intel.com> - 2016-06-23 14:40 +0200
    [docs-next PATCH v2 06/11] kernel-doc: unify all EXPORT_SYMBOL scanning to one place Jani Nikula <jani.nikula@intel.com> - 2016-06-23 14:40 +0200
    [docs-next PATCH v2 10/11] Documentation/sphinx: drop modindex, we don't have python modules Jani Nikula <jani.nikula@intel.com> - 2016-06-23 14:40 +0200
    [docs-next PATCH v2 05/11] kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs Jani Nikula <jani.nikula@intel.com> - 2016-06-23 14:40 +0200
    [docs-next PATCH v2 04/11] kernel-doc: abstract filename mapping Jani Nikula <jani.nikula@intel.com> - 2016-06-23 14:40 +0200
    Re: [docs-next PATCH v2 00/11] Documentation/sphinx follow-up,  again Jonathan Corbet <corbet@lwn.net> - 2016-06-23 16:00 +0200

#1429762 — [docs-next PATCH v2 00/11] Documentation/sphinx follow-up, again

The first 9 patches are just a resend of [1], there's two patches on top
here.

Pull details below.

BR,
Jani.

[1] http://mid.gmane.org/cover.1465567017.git.jani.nikula@intel.com


The following changes since commit 8569de68e79e94cce6709831edd94accb6942ade:

  docs: kernel-doc: Add "example" and "note" to the magic section types (2016-06-09 13:35:05 -0600)

are available in the git repository at:

  git://people.freedesktop.org/~jani/drm sphinx-for-docs-next

for you to fetch changes up to ebc88ef05c825024a5d95285459b8c842c095c0f:

  Documentation: add top level 'make help' output for Sphinx (2016-06-23 15:11:51 +0300)

----------------------------------------------------------------
Jani Nikula (11):
      kernel-doc: remove old debug cruft from dump_section()
      kernel-doc: do not warn about duplicate default section names
      kernel-doc: add missing semi-colons in option parsing
      kernel-doc: abstract filename mapping
      kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs
      kernel-doc: unify all EXPORT_SYMBOL scanning to one place
      Documentation/sphinx: remove unnecessary temporary variable
      Documentation/sphinx: use a more sensible string split in kernel-doc extension
      Documentation/sphinx: add support for specifying extra export files
      Documentation/sphinx: drop modindex, we don't have python modules
      Documentation: add top level 'make help' output for Sphinx

 Documentation/DocBook/Makefile     |  4 +-
 Documentation/Makefile.sphinx      |  8 ++++
 Documentation/index.rst            |  2 -
 Documentation/sphinx/kernel-doc.py | 18 +++++---
 Makefile                           |  2 +
 scripts/kernel-doc                 | 88 +++++++++++++++++++++++++++-----------
 6 files changed, 87 insertions(+), 35 deletions(-)


-- 
2.1.4

[toc] | [next] | [standalone]

#1429765 — [docs-next PATCH v2 11/11] Documentation: add top level 'make help' output for Sphinx

While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 Documentation/DocBook/Makefile | 4 ++--
 Documentation/Makefile.sphinx  | 8 ++++++++
 Makefile                       | 2 ++
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index e0c7e1e0590b..496d4295ec38 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -218,7 +218,7 @@ silent_gen_xml = :
 ###
 # Help targets as used by the top-level makefile
 dochelp:
-	@echo  ' Linux kernel internal documentation in different formats:'
+	@echo  ' Linux kernel internal documentation in different formats (DocBook):'
 	@echo  '  htmldocs        - HTML'
 	@echo  '  pdfdocs         - PDF'
 	@echo  '  psdocs          - Postscript'
@@ -227,7 +227,7 @@ dochelp:
 	@echo  '  installmandocs  - install man pages generated by mandocs'
 	@echo  '  cleandocs       - clean all generated DocBook files'
 	@echo
-	@echo  'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
+	@echo  '  make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
 	@echo  '  valid values for DOCBOOKS are: $(DOCBOOKS)'
 
 
diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index addf32309bc3..810c11f0d37f 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -60,4 +60,12 @@ installmandocs:
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
 
+dochelp:
+	@echo  ' Linux kernel internal documentation in different formats (Sphinx):'
+	@echo  '  htmldocs        - HTML'
+	@echo  '  pdfdocs         - PDF'
+	@echo  '  epubdocs        - EPUB'
+	@echo  '  xmldocs         - XML'
+	@echo  '  cleandocs       - clean all generated files'
+
 endif # HAVE_SPHINX
diff --git a/Makefile b/Makefile
index 8908a51b895a..f7f393c40886 100644
--- a/Makefile
+++ b/Makefile
@@ -1364,6 +1364,8 @@ help:
 	@$(MAKE) $(build)=$(package-dir) help
 	@echo  ''
 	@echo  'Documentation targets:'
+	@$(MAKE) -f $(srctree)/Documentation/Makefile.sphinx dochelp
+	@echo  ''
 	@$(MAKE) -f $(srctree)/Documentation/DocBook/Makefile dochelp
 	@echo  ''
 	@echo  'Architecture specific targets ($(SRCARCH)):'
-- 
2.1.4

[toc] | [prev] | [next] | [standalone]

#1429766 — [docs-next PATCH v2 06/11] kernel-doc: unify all EXPORT_SYMBOL scanning to one place

Scan all input files for EXPORT_SYMBOLs along with the explicitly
specified export files before actually parsing anything.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 scripts/kernel-doc | 18 +++++-------------
 1 file changed, 5 insertions(+), 13 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 9708a87c7069..932b3f34ff06 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -61,10 +61,10 @@ Output format selection (mutually exclusive):
 Output selection (mutually exclusive):
   -export		Only output documentation for symbols that have been
 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
-                        in the same FILE or any -export-file FILE.
+                        in any input FILE or -export-file FILE.
   -internal		Only output documentation for symbols that have NOT been
 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
-                        in the same FILE or any -export-file FILE.
+                        in any input FILE or -export-file FILE.
   -function NAME	Only output documentation for the given function(s)
 			or DOC: section title(s). All other functions and DOC:
 			sections are ignored. May be specified multiple times.
@@ -2792,17 +2792,6 @@ sub process_file($) {
 	return;
     }
 
-    # two passes for -export and -internal
-    if ($output_selection == OUTPUT_EXPORTED ||
-	$output_selection == OUTPUT_INTERNAL) {
-	while (<IN>) {
-	    if (/$export_symbol/o) {
-		$function_table{$2} = 1;
-	    }
-	}
-	seek(IN, 0, 0);
-    }
-
     $. = 1;
 
     $section_counter = 0;
@@ -3110,6 +3099,9 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
 
 if ($output_selection == OUTPUT_EXPORTED ||
     $output_selection == OUTPUT_INTERNAL) {
+
+    push(@export_file_list, @ARGV);
+
     foreach (@export_file_list) {
 	chomp;
 	process_export_file($_);
-- 
2.1.4

[toc] | [prev] | [next] | [standalone]

#1429767 — [docs-next PATCH v2 10/11] Documentation/sphinx: drop modindex, we don't have python modules

The modindex is for python modules.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 Documentation/index.rst | 2 --
 1 file changed, 2 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 71a276f34c7f..1139a7ea39ec 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -18,6 +18,4 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
-
-- 
2.1.4

[toc] | [prev] | [next] | [standalone]

#1429770 — [docs-next PATCH v2 05/11] kernel-doc: add support for specifying extra files for EXPORT_SYMBOLs

If the kernel-doc comments for functions are not in the same file as the
EXPORT_SYMBOL statements, the -export and -internal output selections do
not work as expected. This is typically the case when the kernel-doc
comments are in header files next to the function declarations and the
EXPORT_SYMBOL statements are next to the function definitions in the
source files.

Let the user specify additional source files in which to look for the
EXPORT_SYMBOLs using the new -export-file FILE option, which may be
given multiple times.

The pathological example for this is include/net/mac80211.h, which has
all the kernel-doc documentation for the exported functions defined in a
plethora of source files net/mac80211/*.c.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 scripts/kernel-doc | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 516d95fcefb7..9708a87c7069 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -61,10 +61,10 @@ Output format selection (mutually exclusive):
 Output selection (mutually exclusive):
   -export		Only output documentation for symbols that have been
 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
-			in the same FILE.
+                        in the same FILE or any -export-file FILE.
   -internal		Only output documentation for symbols that have NOT been
 			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
-			in the same FILE.
+                        in the same FILE or any -export-file FILE.
   -function NAME	Only output documentation for the given function(s)
 			or DOC: section title(s). All other functions and DOC:
 			sections are ignored. May be specified multiple times.
@@ -76,6 +76,9 @@ Output selection modifiers:
   -no-doc-sections	Do not output DOC: sections.
   -enable-lineno        Enable output of #define LINENO lines. Only works with
                         reStructuredText format.
+  -export-file FILE     Specify an additional FILE in which to look for
+                        EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
+                        -export or -internal. May be specified multiple times.
 
 Other parameters:
   -v			Verbose output, more warnings and other information.
@@ -336,6 +339,8 @@ use constant {
 my $output_selection = OUTPUT_ALL;
 my $show_not_found = 0;
 
+my @export_file_list;
+
 my @build_time;
 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
@@ -488,6 +493,9 @@ while ($ARGV[0] =~ m/^-(.*)/) {
     } elsif ($cmd eq "-internal") { # only non-exported symbols
 	$output_selection = OUTPUT_INTERNAL;
 	%function_table = ();
+    } elsif ($cmd eq "-export-file") {
+	my $file = shift @ARGV;
+	push(@export_file_list, $file);
     } elsif ($cmd eq "-v") {
 	$verbose = 1;
     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
@@ -2747,6 +2755,25 @@ sub map_filename($) {
     return $file;
 }
 
+sub process_export_file($) {
+    my ($orig_file) = @_;
+    my $file = map_filename($orig_file);
+
+    if (!open(IN,"<$file")) {
+	print STDERR "Error: Cannot open file $file\n";
+	++$errors;
+	return;
+    }
+
+    while (<IN>) {
+	if (/$export_symbol/) {
+	    $function_table{$2} = 1;
+	}
+    }
+
+    close(IN);
+}
+
 sub process_file($) {
     my $file;
     my $identifier;
@@ -3081,6 +3108,14 @@ if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
 	close(SOURCE_MAP);
 }
 
+if ($output_selection == OUTPUT_EXPORTED ||
+    $output_selection == OUTPUT_INTERNAL) {
+    foreach (@export_file_list) {
+	chomp;
+	process_export_file($_);
+    }
+}
+
 foreach (@ARGV) {
     chomp;
     process_file($_);
-- 
2.1.4

[toc] | [prev] | [next] | [standalone]

#1429771 — [docs-next PATCH v2 04/11] kernel-doc: abstract filename mapping

Reduce duplication in follow-up work. No functional changes.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 scripts/kernel-doc | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a6f82c812c15..516d95fcefb7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2730,26 +2730,35 @@ sub local_unescape($) {
 	return $text;
 }
 
-sub process_file($) {
+sub map_filename($) {
     my $file;
-    my $identifier;
-    my $func;
-    my $descr;
-    my $in_purpose = 0;
-    my $initial_section_counter = $section_counter;
     my ($orig_file) = @_;
-    my $leading_space;
 
     if (defined($ENV{'SRCTREE'})) {
 	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
-    }
-    else {
+    } else {
 	$file = $orig_file;
     }
+
     if (defined($source_map{$file})) {
 	$file = $source_map{$file};
     }
 
+    return $file;
+}
+
+sub process_file($) {
+    my $file;
+    my $identifier;
+    my $func;
+    my $descr;
+    my $in_purpose = 0;
+    my $initial_section_counter = $section_counter;
+    my ($orig_file) = @_;
+    my $leading_space;
+
+    $file = map_filename($orig_file);
+
     if (!open(IN,"<$file")) {
 	print STDERR "Error: Cannot open file $file\n";
 	++$errors;
-- 
2.1.4

[toc] | [prev] | [next] | [standalone]

#1429866 — Re: [docs-next PATCH v2 00/11] Documentation/sphinx follow-up, again

On Thu, 23 Jun 2016 15:28:00 +0300
Jani Nikula <jani.nikula@intel.com> wrote:

> The first 9 patches are just a resend of [1], there's two patches on top
> here.

OK, these all look good to me.  Applied to the docs tree, sorry for the
delay.

jon

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web