linux.git/Documentation/sphinx, branch v4.8

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

2016-07-23T10:55:59+00:00

* '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

doc-rst: kernel-doc directive, fix state machine reporter

2016-07-20T22:51:12+00:00

Add a reporter replacement that assigns the correct source name and line
number to a system message, as recorded in a ViewList.

[1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com

Signed-off-by: Markus Heiser 
Tested-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

doc-rst: parse-headers: remove trailing spaces

2016-07-09T12:42:31+00:00

The function that replace references add a "\ " at the end of
references, to avoid the ReST markup parser to not identify
them as references. That works fine except for the end of lines,
as a sequence of { '\', ' ', '\n' } characters makes Sphinx
to ignore the end of line. So, strip those escape/spaces at the
end of lines.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: add kernel-include directive

2016-07-08T12:31:04+00:00

The kernel-include directive is needed to include the auto generated rst
content from a build (pre-) process. E.g. the linux_tv Makefile
generates intermediate reST-files from header files. Since there is a O=
option:

  make O=dir [targets] Locate all output files in "dir"

We need to include intermediate reST files from arbitrary (O=/tmp/foo)
locations:

The 'kernel-include' reST-directive is a replacement for the 'include'
directive. The 'kernel-include' directive expand environment variables
in the path name and allows to include files from arbitrary locations.

.. hint::

  Including files from arbitrary locations (e.g. from '/etc') is a
  security risk for builders. This is why the 'include' directive from
  docutils *prohibit* pathnames pointing to locations *above* the
  filesystem tree where the reST document with the include directive is
  placed.

Substrings of the form $name or ${name} are replaced by the value of
environment variable name. Malformed variable names and references to
non-existing variables are left unchanged.

Signed-off-by: Markus Heiser 
Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: don't do substituition references

2016-07-07T18:13:17+00:00

Add one extra escape character to avoid those warnings:
	Documentation/linux_tv/videodev2.h.rst:6: WARNING: Inline substitution_reference start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: add an option to ignore enum symbols

2016-07-07T18:13:07+00:00

At videodev2.h, we have hundreds of symbols that don't
currently have a reference yet. Let's ignore for how, while
we don't improve those cross-refs.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: better handle comments at the source code

2016-07-07T18:12:48+00:00

We should not let comments to mangle with the symbols
parsing. Unfortunately, videodev2.h has lots of those
in the middle of enums and structs. So, we need to improve
our parser to discard them.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: fix multiline typedef handler

2016-07-07T11:12:57+00:00

The typedef handler should do two things to be generic:
  1) parse typedef enums;
  2) accept both possible syntaxes:
	 typedef struct foo { .. } foo_t;
	 typedef struct { .. } foo_t;

Unfortunately, this is needed to parse some legacy DVB
files, like dvb/audio.h.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: better handle typedefs

2016-07-07T10:22:20+00:00

When typedef is used on its multiline format, we need to
also parse enum and struct in the same line.

Signed-off-by: Mauro Carvalho Chehab

doc-rst: parse-headers: be more formal about the valid symbols

2016-07-07T10:08:32+00:00

Be more formal about the valid symbols that are expected by
the parser, to match what c language expects.

Signed-off-by: Mauro Carvalho Chehab