Commit Graph

634523 Commits

Author SHA1 Message Date
Mauro Carvalho Chehab
79c87c30d0 docs: 00-INDEX: consolidate process/ and admin-guide/ description
Instead of having descriptions for individual files inside
the process/ and admin-guide/ documentation, consolidate them
into one entry per directory, just like other descriptions
inside 00-INDEX.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-05 14:21:29 -07:00
Mauro Carvalho Chehab
f15c323397 scripts: add a script to check if Documentation/00-INDEX is sane
It is easy to forget adding/removing entries at the
Documentation/00-INDEX file. In a matter of fact, even before
ReST conversion, people use to forget adding things here, as
there are lots of missing stuff out there.

Now that we're doing a hard work converting entries to ReST,
and while this hole file is not outdated, it is good to have
some tool that would help to verify that this file is kept
updated.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-05 14:21:24 -07:00
Kevin Peng
20b786eb25 Docs: change sh -> awk in REPORTING-BUGS
scripts/ver_linux has been rewritten as an awk script; update
documentation to reflect this fact.

Signed-off-by: Kevin Peng <kkpengboy@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-05 14:18:48 -07:00
Lukas Wunner
aad800403a Documentation/core-api/device_link: Add initial documentation
Document device links as introduced in v4.10 with commits:
    4bdb35506b ("driver core: Add a wrapper around
                   __device_release_driver()")
    9ed9895370 ("driver core: Functional dependencies tracking
                   support")
    8c73b42884 ("PM / sleep: Make async suspend/resume of devices use
                   device links")
    21d5c57b37 ("PM / runtime: Use device links")
    baa8809f60 ("PM / runtime: Optimize the use of device links")

Signed-off-by: Lukas Wunner <lukas@wunner.de>
[ jc: Moved from core-api to driver-api ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-05 14:14:55 -07:00
Mauro Carvalho Chehab
2ba90ccca7 core-api: remove an unexpected unident
As complained by Sphinx:
	Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-01 10:46:01 -07:00
Balbir Singh
c3cbd075fc ppc/idle: Add documentation for powersave=off
Update kernel-parameters.txt to add Documentation
for powersave=off.

Signed-off-by: Balbir Singh <bsingharora@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-01 10:45:16 -07:00
Sanjeev
7d56f0facd Doc: Correct typo, "Introdution" => "Introduction"
This corrects a set of spelling mistakes, probably from an
automated conversion.

Signed-off-by: Sanjeev Gupta <ghane0@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-12-01 10:44:08 -07:00
Jonathan Corbet
2fc9254d0c Merge branch 'silvio' into docs-next 2016-11-30 17:46:23 -07:00
Silvio Fricke
326bc876fe Documentation/atomic_ops.txt: convert to ReST markup
... and move to core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:40:52 -07:00
Silvio Fricke
c232694ec1 Documentation/local_ops.txt: convert to ReST markup
... and move to core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:40:48 -07:00
Silvio Fricke
c3cbf1a704 Documentation/assoc_array.txt: convert to ReST markup
... and move to Documentation/core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:40:43 -07:00
Mauro Carvalho Chehab
c339665666 docs-rst: parse-headers.pl: cleanup the documentation
Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:08:09 -07:00
Mauro Carvalho Chehab
293fbd4fef docs-rst: fix media cleandocs target
The builddir prefix was missing on make cleandocs. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:08:03 -07:00
Mauro Carvalho Chehab
bf5bfe85ec docs-rst: media/Makefile: reorganize the rules
Better organize the media/Makefile, in order to better
split what's related to image conversion from the ones
related to parse-headers.pl.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:07:58 -07:00
Mauro Carvalho Chehab
ec868e4ee2 docs-rst: media: build SVG from graphviz files
Instead of keeping both SVG and graphviz files, dynamically
build SVG from its graphviz sources.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:07:54 -07:00
Mauro Carvalho Chehab
ffbdad94d0 docs-rst: replace bayer.png by a SVG image
SVG images are scalable, with makes easier to output on
different formats.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:07:48 -07:00
Mauro Carvalho Chehab
86e6808abb docs-rst: replace the selection.png by a SVG image
bitmap images don't scale too well. So, replace it by a SVG
image, written in inkscape. I'm using the 2009's temporary
logo.svg image from 8032b526d1 ("linux.conf.au 2009: Tuz"),
with a Tasmanian Devil wearing a tux mask.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:07:44 -07:00
Mauro Carvalho Chehab
394709da73 docs-rst: convert pipeline to SVG format
The pipeline image was produced from some dot file that has
long missed. Create a pipeline.dot with the graph and convert
it to SVG. As we're planning to add future support for graphviz
graphics, also store the .dot file on the tree, as this will
make easier when we add such Sphinx extension.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:07:29 -07:00
Mauro Carvalho Chehab
2bd658de40 docs-rst: nv12mt zigzag images: replace by SVG images
Instead of using bitmap images to show the zigzag macroblock
parsing, replace it by a SVG ones, with is scalable.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:03:23 -07:00
Mauro Carvalho Chehab
16bc3bfb23 svg files: cleanup them
Use sans-serif font on all documents, split text lines,
ungroup elements, and do other misc cleanups, in order to make
all of them to look better, and to have smaller columns inside
their lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:01:57 -07:00
Mauro Carvalho Chehab
76cf11aa15 convert more media images to SVG
Using vectorial graphics provide a better visual. As those images
are originally using a vectorial graphics input at the pdf files,
use them, from an old media tree repository, converting them to SVG.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-30 17:01:33 -07:00
Jonathan Corbet
d6ba7a9c8b doc: Sphinxify the tracepoint docbook
Convert the tracepoint docbook template to RST and add it to the core-api
manual.  No changes to the actual text beyond the mechanical formatting
conversion.

Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:44:23 -07:00
Jonathan Corbet
8da3dc5334 doc: debugobjects: actually pull in the kerneldoc comments
Add the appropriate markup to get the kerneldoc comments out of
lib/debugobjects.c that have never seen the light of day until now.

A logical next step, left for the reader at the moment, is to move the
function descriptions *out* of debug-objects.rst and into the kerneldoc
comments themselves.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:44:14 -07:00
Jonathan Corbet
93dc3a112b doc: Convert the debugobjects DocBook template to sphinx
A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.

Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules.  It doesn't work here either :)

Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:44:04 -07:00
Jonathan Corbet
0bb33e25e5 docs: Move the 802.11 guide into the driver-api manual
Put this documentation with the other driver docs and try to keep the top
level reasonably clean.

Cc: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-29 14:41:49 -07:00
Dan Carpenter
388f9b20f9 Documentation/process/howto: Only send regression fixes after -rc1
The original text was not clear if white space or other harmless patches
should be merged in -rc kernels.  The discussion at Kernel Summit said
that we should be more strict about sending regression fixes only.

Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-28 17:24:32 -07:00
Chao Fan
9c240d7576 Change the document about iowait
The iowait is not reliable by reading from /proc/stat, so this
method to get iowait is not suggested. And we mark it in the
document.

Signed-off-by: Cao Jin <caoj.fnst@cn.fujitsu.com>
Signed-off-by: Chao Fan <fanc.fnst@cn.fujitsu.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:38:58 -07:00
Jonathan Corbet
ca9667fcc8 Merge branch 'mauro-doc' into docs-next 2016-11-19 10:28:58 -07:00
Mauro Carvalho Chehab
2dde123b23 parse-headers.rst: add an introduction to the man page
The pod2rst tool generated a man page for parse-headers.pl
script, but it is better to put it into some context.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:15 -07:00
Mauro Carvalho Chehab
327f5a754a parse-headers.pl: add documentation for this script
Provide a man page for parse-headers.pl, describing
how to use it.

The documentation on ReST format was generated via pod2rst:
	http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:08 -07:00
Mauro Carvalho Chehab
1dc4bbf0b2 docs-rst: doc-guide: split the kernel-documentation.rst contents
Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:22:04 -07:00
Daniel Vetter
38f985e3c9 doc: Document the new inline struct member kernel-doc style
We don't just need better doc toolchains, we also need better docs for
our doc toolchain!

v2: Make sure we don't have foo twice (Jani).

Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-19 10:17:12 -07:00
Jonathan Corbet
726d661fea Merge remote-tracking branch 'sound/topic/restize-docs' into sound
Bring in the sphinxification of the sound documentation.
2016-11-18 16:19:28 -07:00
Jonathan Corbet
917fef6f7e Linux 4.9-rc4
-----BEGIN PGP SIGNATURE-----
 
 iQEcBAABAgAGBQJYHmoCAAoJEHm+PkMAQRiG7RMIAI2i7Y5hpL5yCxK5AFaL4u/G
 KxXfp1B1UanUTgjOmd7zGqtDYcFX9t7GTTUFixQ7/9Opr4PD9qbnatoDGSc3xjbT
 msDgA1B78F1/Q3kHWfeGq32MihQ4mj5NwUCo+igUcUvvWG7mHgzErj/Nh5RoobQX
 p/izdpTbrw3GX6xXB8olbG7XWHaVye/+TT3q6+gmgm8I/QEujcLeGoycE0zlhPN8
 FG/JX76At/+ZM2Py7Oxo3k+oKL9CHrtOQYDp/wN0uslV5eYvvkZz0/M1HMOGZt+c
 gZU5jzM17K7C4Nzo06WAuBU9wUBGc25m+cPicLlOmljnzfU+f50SKaDjZq3p7QI=
 =2KUF
 -----END PGP SIGNATURE-----

Merge tag 'v4.9-rc4' into sound

Bring in -rc4 patches so I can successfully merge the sound doc changes.
2016-11-18 16:13:41 -07:00
Jani Nikula
0c9aa20957 kernel-doc: add support for one line inline struct member doc comments
kernel-doc supports documenting struct members "inline" since
a4c6ebede2 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/**
		 * @bar: member documentation
		 */
		int bar;
	};

Add support for one line inline comments:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/** @bar: member documentation */
		int bar;
	};

Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.

Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:30:27 -07:00
Brian Norris
dc92726e7f docs/completion.txt: drop dangling reference to completions-design.txt
Per the original author, the proposed document was never deemed
necessary, and the important bits got merged into completion.txt. Let's
just stop confusing readers by pointing at a nonexistent doc.

Signed-off-by: Brian Norris <briannorris@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:27:50 -07:00
Oliver Neukum
dd0b38d8ee Documentation: convert USB to new format
This is a conversion of the USB documentation to the Sphinx format.
No content was altered or reformatted.

Signed-off-by: Oliver <oneukum@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:20:56 -07:00
Mark Rutland
01e4644203 Documentation: circular-buffers: use READ_ONCE()
While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the circular buffer documentation uses the latter
exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use
READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
circular buffer documentation.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Acked-by: David Howells <dhowells@redhat.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:17:45 -07:00
Mark Rutland
47f4212210 Documentation: atomic_ops: use {READ,WRITE}_ONCE()
While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Will Deacon <will.deacon@arm.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:17:03 -07:00
Jonathan Corbet
22917b992d docs: Add more manuals to the PDF build
There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 16:07:02 -07:00
Jonathan Corbet
3ed3e130ea Merge branch 'mauro-pdf' into docs-next
Mauro says:

This series address a series of errors during PDF generation from
media documentation.

The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.

The next two patches fix PDF output issues with subdev-formats.rst.

The next 3 patches fix image includes and their output for PDF.

It is aligned with Linus request of not having binary-generated images
from their SVG source codes.

I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.

It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.

[jc: added a commit fixing up a "make cleandocs" warning]
2016-11-16 15:39:56 -07:00
Jonathan Corbet
c54b6b3779 docs: Avoid warning on cleandocs
Recent Makefile changes added an rm command without the requisite "-f",
leading to warnings if the files do not exist.  Make it be quiet again.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:38:03 -07:00
Mauro Carvalho Chehab
15a04d4e76 docs-rst: auto-generate PDF image files
The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:59 -07:00
Mauro Carvalho Chehab
f390293479 docs-rst: convert gif files to png
Right now, media is using two different formats for bitmap
images: GIF and PNG. Let's use just one, to make it simpler when
building with Sphinx.

As PNG is usually better than GIF, let's use it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:49 -07:00
Mauro Carvalho Chehab
00e99ed2c8 convert some images from png to svg
SVG images are nicer, as they can easily be scaled. Also, they're
written in text, with makes easier to work.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:42 -07:00
Mauro Carvalho Chehab
346dabfee0 subdev-formats.rst: add missing columns to tabularcolumns
There are several missing columns on the size specification,
causing LaTeX to complain on interactive mode.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:25 -07:00
Mauro Carvalho Chehab
ce998e6fba subdev-formats.rst: don't use adjustbox on a longtable
adjustbox doesn't work on longtables. Also, this
causes an error on LaTeX in interactive mode.

So, use, instead, a tiny font.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:18 -07:00
Mauro Carvalho Chehab
e2a91f4f42 docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+
PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.

The solution is to redefine the \DURole macro.

However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.

Tested by building the documentation on interactive mode:
	make PDFLATEX=xelatex -C Documentation/output/./latex

Fixes: e61a39baf7 ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-16 15:20:12 -07:00
Jonathan Corbet
f5ff9b63d4 MAINTAINERS: The Chinese documentation moved
Update the F: line accordingly.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-13 12:24:59 -07:00
SeongJae Park
ba42c574fc Documentation: Add HOWTO Korean translation into rst based build system
This commit adds Korean translation of HOWTO document into rst based
documentation build system.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-11-13 11:55:02 -07:00