[PULL] Documentation for 4.8

From: Jonathan Corbet
Date: Mon Jul 25 2016 - 08:36:59 EST

The following changes since commit

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:


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

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