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

Pull documentation updates from Jonathan Corbet:
 "After a fair amount of churn in the last couple of cycles, docs are
  taking it easier this time around. Lots of fixes and some new
  documentation, but nothing all that radical. Perhaps the most
  interesting change for many is the scripts/sphinx-pre-install tool
  from Mauro; it will tell you exactly which packages you need to
  install to get a working docs toolchain on your system.

  There are two little patches reaching outside of Documentation/; both
  just tweak kerneldoc comments to eliminate warnings and fix some
  dangling doc pointers"

* 'docs-next' of git://git.lwn.net/linux: (52 commits)
  Documentation/sphinx: fix kernel-doc decode for non-utf-8 locale
  genalloc: Fix an incorrect kerneldoc comment
  doc: Add documentation for the genalloc subsystem
  assoc_array: fix path to assoc_array documentation
  kernel-doc parser mishandles declarations split into lines
  docs: ReSTify table of contents in core.rst
  docs: process: drop git snapshots from applying-patches.rst
  Documentation:input: fix typo
  swap: Remove obsolete sentence
  sphinx.rst: Allow Sphinx version 1.6 at the docs
  docs-rst: fix verbatim font size on tables
  Documentation: stable-kernel-rules: fix broken git urls
  rtmutex: update rt-mutex
  rtmutex: update rt-mutex-design
  docs: fix minimal sphinx version in conf.py
  docs: fix nested numbering in the TOC
  NVMEM documentation fix: A minor typo
  docs-rst: pdf: use same vertical margin on all Sphinx versions
  doc: Makefile: if sphinx is not found, run a check script
  docs: Fix paths in security/keys
  ...

2 files changed, 613 insertions, 0 deletions

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 6e36b7889001..9d3eafea58f0 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2226,6 +2226,7 @@ sub dump_enum($$) {
     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
         $declaration_name = $1;
         my $members = $2;
+        $members =~ s/\s+$//;
 
         foreach my $arg (split ',', $members) {
             $arg =~ s/^\s*(\w+).*/$1/;
@@ -2766,6 +2767,9 @@ sub process_proto_type($$) {
 
     while (1) {
         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
+            if( length $prototype ) {
+                $prototype .= " "
+            }
             $prototype .= $1 . $2;
             ($2 eq '{') && $brcount++;
             ($2 eq '}') && $brcount--;
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
new file mode 100755
index 000000000000..677756ae34c9
--- /dev/null
+++ b/scripts/sphinx-pre-install
@@ -0,0 +1,609 @@
+#!/usr/bin/perl
+use strict;
+
+# Copyright (c) 2017 Mauro Carvalho Chehab <mchehab@kernel.org>
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+my $virtenv_dir = "sphinx_1.4";
+my $requirement_file = "Documentation/sphinx/requirements.txt";
+
+#
+# Static vars
+#
+
+my %missing;
+my $system_release;
+my $need = 0;
+my $optional = 0;
+my $need_symlink = 0;
+my $need_sphinx = 0;
+my $install = "";
+
+#
+# Command line arguments
+#
+
+my $pdf = 1;
+my $virtualenv = 1;
+
+#
+# List of required texlive packages on Fedora and OpenSuse
+#
+
+my %texlive = (
+        'adjustbox.sty'      => 'texlive-adjustbox',
+        'amsfonts.sty'       => 'texlive-amsfonts',
+        'amsmath.sty'        => 'texlive-amsmath',
+        'amssymb.sty'        => 'texlive-amsfonts',
+        'amsthm.sty'         => 'texlive-amscls',
+        'anyfontsize.sty'    => 'texlive-anyfontsize',
+        'atbegshi.sty'       => 'texlive-oberdiek',
+        'bm.sty'             => 'texlive-tools',
+        'capt-of.sty'        => 'texlive-capt-of',
+        'cmap.sty'           => 'texlive-cmap',
+        'ecrm1000.tfm'       => 'texlive-ec',
+        'eqparbox.sty'       => 'texlive-eqparbox',
+        'eu1enc.def'         => 'texlive-euenc',
+        'fancybox.sty'       => 'texlive-fancybox',
+        'fancyvrb.sty'       => 'texlive-fancyvrb',
+        'float.sty'          => 'texlive-float',
+        'fncychap.sty'       => 'texlive-fncychap',
+        'footnote.sty'       => 'texlive-mdwtools',
+        'framed.sty'         => 'texlive-framed',
+        'luatex85.sty'       => 'texlive-luatex85',
+        'multirow.sty'       => 'texlive-multirow',
+        'needspace.sty'      => 'texlive-needspace',
+        'palatino.sty'       => 'texlive-psnfss',
+        'parskip.sty'        => 'texlive-parskip',
+        'polyglossia.sty'    => 'texlive-polyglossia',
+        'tabulary.sty'       => 'texlive-tabulary',
+        'threeparttable.sty' => 'texlive-threeparttable',
+        'titlesec.sty'       => 'texlive-titlesec',
+        'ucs.sty'            => 'texlive-ucs',
+        'upquote.sty'        => 'texlive-upquote',
+        'wrapfig.sty'        => 'texlive-wrapfig',
+);
+
+#
+# Subroutines that checks if a feature exists
+#
+
+sub check_missing(%)
+{
+        my %map = %{$_[0]};
+
+        foreach my $prog (sort keys %missing) {
+                my $is_optional = $missing{$prog};
+
+                if ($is_optional) {
+                        print "Warning: better to also install \"$prog\".\n";
+                } else {
+                        print "ERROR: please install \"$prog\", otherwise, build won't work.\n";
+                }
+                if (defined($map{$prog})) {
+                        $install .= " " . $map{$prog};
+                } else {
+                        $install .= " " . $prog;
+                }
+        }
+
+        $install =~ s/^\s//;
+}
+
+sub add_package($$)
+{
+        my $package = shift;
+        my $is_optional = shift;
+
+        $missing{$package} = $is_optional;
+        if ($is_optional) {
+                $optional++;
+        } else {
+                $need++;
+        }
+}
+
+sub check_missing_file($$$)
+{
+        my $file = shift;
+        my $package = shift;
+        my $is_optional = shift;
+
+        return if(-e $file);
+
+        add_package($package, $is_optional);
+}
+
+sub findprog($)
+{
+        foreach(split(/:/, $ENV{PATH})) {
+                return "$_/$_[0]" if(-x "$_/$_[0]");
+        }
+}
+
+sub check_program($$)
+{
+        my $prog = shift;
+        my $is_optional = shift;
+
+        return if findprog($prog);
+
+        add_package($prog, $is_optional);
+}
+
+sub check_perl_module($$)
+{
+        my $prog = shift;
+        my $is_optional = shift;
+
+        my $err = system("perl -M$prog -e 1 2>/dev/null /dev/null");
+        return if ($err == 0);
+
+        add_package($prog, $is_optional);
+}
+
+sub check_python_module($$)
+{
+        my $prog = shift;
+        my $is_optional = shift;
+
+        my $err = system("python3 -c 'import $prog' 2>/dev/null /dev/null");
+        return if ($err == 0);
+        my $err = system("python -c 'import $prog' 2>/dev/null /dev/null");
+        return if ($err == 0);
+
+        add_package($prog, $is_optional);
+}
+
+sub check_rpm_missing($$)
+{
+        my @pkgs = @{$_[0]};
+        my $is_optional = $_[1];
+
+        foreach my $prog(@pkgs) {
+                my $err = system("rpm -q '$prog' 2>/dev/null >/dev/null");
+                add_package($prog, $is_optional) if ($err);
+        }
+}
+
+sub check_pacman_missing($$)
+{
+        my @pkgs = @{$_[0]};
+        my $is_optional = $_[1];
+