[PULL] Documentation for 4.8

[Jonathan Corbet]

The following changes since commit
1a695a905c18548062509178b98bc91e67510864:

  Linux 4.7-rc1 (2016-05-29 09:29:24 -0700)

are available in the git repository at:

  git://git.lwn.net/linux.git tags/docs-for-linus

for you to fetch changes up to a88b1672d4ddf9895eb53e6980926d5e960dea8e:

  doc-rst: kernel-doc: fix handling of address_space tags (2016-07-22 15:34:24 -0600)

----------------------------------------------------------------
Some big changes this month, headlined by the addition of a new formatted
documentation mechanism based on the Sphinx system.  The objectives here
are to make it easier to create better-integrated (and more attractive)
documents while (eventually) dumping our one-of-a-kind, cobbled-together
system for something that is widely used and maintained by others.  There's
a fair amount of information what's being done, why, and how to use it in:

  https://lwn.net/Articles/692704/
  https://lwn.net/Articles/692705/

Closer to home, Documentation/kernel-documentation.rst describes how it
works.

For now, the new system exists alongside the old one; you should soon see
the GPU documentation converted over in the DRM pull and some significant
media conversion work as well.  Once all the docs have been moved over and
we're convinced that the rough edges (of which are are a few) have been
smoothed over, the DocBook-based stuff should go away.

Primary credit is to Jani Nikula for doing the heavy lifting to make this
stuff actually work; there has also been notable effort from Markus Heiser,
Daniel Vetter, and Mauro Carvalho Chehab.

Expect a couple of conflicts on the new index.rst file over the course of
the merge window; they are trivially resolvable.  That file may be a bit of
a conflict magnet in the short term, but I don't expect that situation to
last for any real length of time.

Beyond that, of course, we have the usual collection of tweaks, updates,
and typo fixes.

----------------------------------------------------------------
Andy Deng (1):
      Documentation/zh_CN: update Chinese version CodingStyle

Brian Norris (1):
      doc: clarify that trace_events= takes a comma-separated list

Daniel Vetter (8):
      doc/sphinx: Pass right filename as source
      scripts/kernel-doc: Remove duplicated DOC: start handling
      doc/sphinx: Stop touching state_machine internals
      scripts/kernel-doc: Also give functions symbolic names
      scripts/kernel-doc: Add option to inject line numbers
      doc/sphinx: Track line-number of starting blocks
      kernel-doc: Fix up warning output
      doc/sphinx: Enable keep_warnings

Eric Wheeler (1):
      bcache: documentation formatting, edited for clarity, stripe alignment notes

Jani Nikula (45):
      kernel-doc/rst: fix use of uninitialized value
      kernel-doc: support printing exported and non-exported symbols
      Documentation/sphinx: add basic working Sphinx configuration and build
      Documentation: add .gitignore
      Documentation/sphinx: add Sphinx kernel-doc directive extension
      Documentation/sphinx: configure the kernel-doc extension
      Documentation/sphinx: set version and release properly
      sphinx: update docbook->rst conversion script match C domain spec
      Documentation/sphinx: nicer referencing of struct in docbook->rst conversion
      kernel-doc: add names for states and substates
      kernel-doc: add names for output selection
      kernel-doc/rst: do not output DOC: section titles for requested ones
      kernel-doc/rst: reference functions according to C domain spec
      kernel-doc/rst: &foo references are more universal than structs
      kernel-doc/rst: add support for &union foo and &typedef foo references
      kernel-doc/rst: add support for struct/union/enum member references
      kernel-doc/rst: drop redundant unescape in highlighting
      kernel-doc/rst: highlight function/struct/enum purpose lines too
      kernel-doc: do not regard $, %, or & prefixes as special in section names
      kernel-doc: fix wrong code indentation
      kernel-doc/rst: blank lines in output are not needed
      kernel-doc: strip leading blank lines from inline doc comments
      kernel-doc/rst: change the output layout
      kernel-doc: improve handling of whitespace on the first line param description
      kernel-doc: strip leading whitespace from continued param descs
      kernel-doc/rst: use *undescribed* instead of _undescribed_
      kernel-doc/rst: remove fixme comment
      kernel-doc: limit the "section header:" detection to a select few
      kernel-doc: concatenate contents of colliding sections
      kernel-doc: reset contents and section harder
      Documentation/sphinx: fix kernel-doc extension on python3
      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: add meta-documentation for Sphinx and kernel-doc
      Documentation: add cleanmediadocs to the documentation targets
      Documentation/sphinx: skip build if user requested specific DOCBOOKS

Javier Martinez Canillas (1):
      Documentation: Fix some grammar mistakes in sync_file.txt

Jerome Marchand (1):
      Documentation: add watermark_scale_factor to the list of vm systcl file

Jonathan Corbet (7):
      sphinx: cheesy script to convert .tmpl files
      Merge branch 'sphinx-for-docs-next' into doc/4.8
      docs: kernel-doc: Add "example" and "note" to the magic section types
      Add .pyc files to .gitignore
      docs: Get rid of some kernel-documentation warnings
      docs: deprecate kernel-doc-nano-HOWTO.txt
      Revert "doc/sphinx: Enable keep_warnings"

Kees Cook (1):
      docs: self-protection: rename "leak" to "exposure"

Marc MERLIN (1):
      bcache: documentation updates and corrections

Markus Heiser (2):
      doc-rst: flat-table directive - initial implementation
      doc-rst: kernel-doc directive, fix state machine reporter

Masanari Iida (3):
      Doc: PM: Fix a typo in intel_powerclamp.txt
      Doc: ocfs: Fix typo in filesystems/ocfs2-online-filecheck.txt
      workqueue: Fix a typo in workqueue.txt

Mauro Carvalho Chehab (2):
      doc-rst: add an option to ignore DocBooks when generating docs
      doc-rst: kernel-doc: fix handling of address_space tags

Michal Nazarewicz (1):
      Documentation: tiny typo fix in usb/gadget_multi.txt

Mike Danese (1):
      mpssd: fix buffer overflow warning

Niklas SÃderlund (1):
      Documentation: dmaengine: fix typo for device_resume

Tiezhu Yang (1):
      Documentation: fix wrong value in md.txt

 Documentation/.gitignore                           |   2 +
 Documentation/00-INDEX                             |   4 +-
 Documentation/CodingStyle                          |   2 +-
 Documentation/DocBook/Makefile                     |  30 +-
 Documentation/Makefile.sphinx                      |  78 +++
 Documentation/bcache.txt                           | 197 ++++++-
 Documentation/conf.py                              | 414 +++++++++++++
 Documentation/development-process/4.Coding         |   2 +-
 Documentation/dmaengine/provider.txt               |   2 +-
 .../filesystems/ocfs2-online-filecheck.txt         |  10 +-
 Documentation/index.rst                            |  22 +
 Documentation/kernel-doc-nano-HOWTO.txt            |   3 +
 Documentation/kernel-documentation.rst             | 654 +++++++++++++++++++++
 Documentation/kernel-parameters.txt                |   5 +-
 Documentation/md.txt                               |   2 +-
 Documentation/mic/mpssd/mpssd.c                    |   4 +-
 Documentation/security/self-protection.txt         |  28 +-
 Documentation/sphinx/convert_template.sed          |  18 +
 Documentation/sphinx/kernel-doc.py                 | 141 +++++
 Documentation/sphinx/post_convert.sed              |  23 +
 Documentation/sphinx/rstFlatTable.py               | 365 ++++++++++++
 Documentation/sphinx/tmplcvt                       |  19 +
 Documentation/sync_file.txt                        |   6 +-
 Documentation/sysctl/vm.txt                        |   1 +
 Documentation/thermal/intel_powerclamp.txt         |   2 +-
 Documentation/usb/gadget_multi.txt                 |   2 +-
 Documentation/workqueue.txt                        |   2 +-
 Documentation/zh_CN/CodingStyle                    | 581 ++++++++++--------
 Makefile                                           |   7 +-
 scripts/kernel-doc                                 | 457 +++++++++-----
 30 files changed, 2653 insertions(+), 430 deletions(-)
 create mode 100644 Documentation/.gitignore
 create mode 100644 Documentation/Makefile.sphinx
 create mode 100644 Documentation/conf.py
 create mode 100644 Documentation/index.rst
 create mode 100644 Documentation/kernel-documentation.rst
 create mode 100644 Documentation/sphinx/convert_template.sed
 create mode 100644 Documentation/sphinx/kernel-doc.py
 create mode 100644 Documentation/sphinx/post_convert.sed
 create mode 100644 Documentation/sphinx/rstFlatTable.py
 create mode 100755 Documentation/sphinx/tmplcvt