Merge branch 'docs-next' of git://git.lwn.net/linux into topic/docs-next

* 'docs-next' of git://git.lwn.net/linux:
  doc-rst: kernel-doc: fix handling of address_space tags
  Revert "doc/sphinx: Enable keep_warnings"
  doc-rst: kernel-doc directive, fix state machine reporter
  docs: deprecate kernel-doc-nano-HOWTO.txt
  doc/sphinx: Enable keep_warnings
  Documentation: add watermark_scale_factor to the list of vm systcl file
  kernel-doc: Fix up warning output
  docs: Get rid of some kernel-documentation warnings

Documentation/00-INDEX

@@ -255,10 +255,10 @@ kbuild/
 	- directory with info about the kernel build process.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
-kernel-doc-nano-HOWTO.txt
-	- mini HowTo on generation and location of kernel documentation files.
 kernel-docs.txt
 	- listing of various WWW + books that document kernel internals.
+kernel-documentation.rst
+	- how to write and format reStructuredText kernel documentation
 kernel-parameters.txt
 	- summary listing of command line / boot prompt args for the kernel.
 kernel-per-CPU-kthreads.txt

Documentation/CodingStyle

@@ -458,7 +458,7 @@ of the function, telling people what it does, and possibly WHY it does
 it.
 
 When commenting the kernel API functions, please use the kernel-doc format.
-See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
+See the files Documentation/kernel-documentation.rst and scripts/kernel-doc
 for details.
 
 Linux style for comments is the C89 "/* ... */" style.

Documentation/development-process/4.Coding

@@ -346,7 +346,7 @@ which have not been so documented, there is no harm in adding kerneldoc
 comments for the future; indeed, this can be a useful activity for
 beginning kernel developers.  The format of these comments, along with some
 information on how to create kerneldoc templates can be found in the file
-Documentation/kernel-doc-nano-HOWTO.txt.
+Documentation/kernel-documentation.rst.
 
 Anybody who reads through a significant amount of existing kernel code will
 note that, often, comments are most notable by their absence.  Once again,

Documentation/kernel-doc-nano-HOWTO.txt

@@ -1,3 +1,6 @@
+NOTE: this document is outdated and will eventually be removed.  See
+Documentation/kernel-documentation.rst for current information.
+
 kernel-doc nano-HOWTO
 =====================
 

Documentation/kernel-documentation.rst

@@ -366,6 +366,8 @@ Domain`_ references.
 Cross-referencing from reStructuredText
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. highlight:: none
+
 To cross-reference the functions and types defined in the kernel-doc comments
 from reStructuredText documents, please use the `Sphinx C Domain`_
 references. For example::
@@ -388,6 +390,8 @@ For further details, please refer to the `Sphinx C Domain`_ documentation.
 Function documentation
 ----------------------
 
+.. highlight:: c
+
 The general format of a function and function-like macro kernel-doc comment is::
 
   /**
@@ -568,6 +572,8 @@ DocBook XML [DEPRECATED]
 Converting DocBook to Sphinx
 ----------------------------
 
+.. highlight:: none
+
 Over time, we expect all of the documents under ``Documentation/DocBook`` to be
 converted to Sphinx and reStructuredText. For most DocBook XML documents, a good
 enough solution is to use the simple ``Documentation/sphinx/tmplcvt`` script,

Documentation/sphinx/kernel-doc.py

@@ -37,6 +37,7 @@ from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import directives
 from sphinx.util.compat import Directive
+from sphinx.ext.autodoc import AutodocReporter
 
 class KernelDocDirective(Directive):
     """Extract kernel-doc comments from the specified file"""
@@ -117,12 +118,17 @@ class KernelDocDirective(Directive):
                     lineoffset += 1
 
             node = nodes.section()
-            node.document = self.state.document
+            buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
-            self.state.nested_parse(result, self.content_offset, node)
+            self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
+            self.state.memo.title_styles, self.state.memo.section_level = [], 0
+            try:
+                self.state.nested_parse(result, 0, node, match_titles=1)
+            finally:
+                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
 
             return node.children
 
-        except Exception as e:
+        except Exception as e:  # pylint: disable=W0703
             env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
                          (" ".join(cmd), str(e)))
             return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]

Documentation/sysctl/vm.txt

@@ -61,6 +61,7 @@ Currently, these files are in /proc/sys/vm:
 - swappiness
 - user_reserve_kbytes
 - vfs_cache_pressure
+- watermark_scale_factor
 - zone_reclaim_mode
 
 ==============================================================

Documentation/zh_CN/CodingStyle

@@ -399,7 +399,7 @@ C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pasca
 些事情的原因。
 
 当注释内核API函数时，请使用 kernel-doc 格式。请看
-Documentation/kernel-doc-nano-HOWTO.txt和scripts/kernel-doc 以获得详细信息。
+Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
 
 Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
 

scripts/kernel-doc

@@ -1848,6 +1848,10 @@ sub output_function_rst(%) {
 	}
 	$count++;
 	$type = $args{'parametertypes'}{$parameter};
+
+	# RST doesn't like address_space tags at function prototypes
+	$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
+
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print $1 . $parameter . ") (" . $2;
@@ -2994,7 +2998,7 @@ sub process_file($) {
 		    }
 		} elsif ($inline_doc_state == STATE_INLINE_NAME) {
 		    $inline_doc_state = STATE_INLINE_ERROR;
-		    print STDERR "Warning(${file}:$.): ";
+		    print STDERR "${file}:$.: warning: ";
 		    print STDERR "Incorrect use of kernel-doc format: $_";
 		    ++$warnings;
 		}