As kdbg.rst uses the ".. important::" annotation, let's define a
color for PDF output.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

- Manually adjusted to use ..note and ..warning
- Minor fixes for it to be parsed without errors
- Use **bold** for emphasis.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Now that all files under Documentation/input follows the ReST markup
language, rename them to *.rst and create a book for the Linux Input
subsystem.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NDmitry Torokhov <dmitry.torokhov@gmail.com>

Using the development version of sphinx caused the parsing of the
version to fail.
Signed-off-by: NRémy Léone <remy.leone@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This patch brings scalable figure, image handling and a concept to
embed *render* markups:

* DOT (http://www.graphviz.org)
* SVG

For image handling use the 'image' replacement::

    .. kernel-image::  svg_image.svg
       :alt:    simple SVG image

For figure handling use the 'figure' replacement::

    .. kernel-figure::  svg_image.svg
       :alt:    simple SVG image

       SVG image example

Embed *render* markups (or languages) like Graphviz's **DOT** is
provided by the *render* directive.::

  .. kernel-render:: DOT
     :alt: foobar digraph
     :caption: Embedded **DOT** (Graphviz) code.

     digraph foo {
      "bar" -> "baz";
     }

The *render* directive is a concept to integrate *render* markups and
languages, yet supported markups:

* DOT: render embedded Graphviz's **DOT**
* SVG: render embedded Scalable Vector Graphics (**SVG**)

Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Tested-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5)
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6)
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

With Sphinx 1.5.3 I get the warning:

	WARNING: primary_domain 'C' not found, ignored.

It seems that domain names in Sphinx are case-sensitive and for the C
domain the name must be lower case.
Signed-off-by: NJohn Keeping <john@metanate.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

It had gone stale, of course, as it would every year, a single date doesn't
really cover things, and the date isn't really needed anyway.

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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

There were a few manuals that weren't being built in PDF format, but
there's no reason not to...
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: e61a39ba ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Set the default highlight language to "none", i.e. do not try to guess
the language and do automatic syntax highlighting on literal blocks.

Eyeballing around the generated documentation, we don't seem to actually
have a lot of literal blocks that would benefit from syntax
highlighting. The C code blocks we do have are typically very short, and
most of the literal blocks are things that shouldn't be highlighted (or,
do not have a pygments lexer). This seems to be true for literal blocks
both in the rst source files and in source code comments.

Not highlighting code is never wrong, but guessing the language wrong
almost invariably leads to silly or confusing highlighting.

At the time of writing, admin-guide/oops-tracing.rst and
admin-guide/ramoops.rst contain good examples of 1) a small C code
snippet not highlighted, 2) a hex dump highligted as who knows what, 3)
device tree block highlighted as C or maybe Python, 4) a terminal
interaction highlighted as code in some language, and finally, 5) some C
code snippets correctly identified as C. I think we're better off
disabling language guessing, and going by explicitly identified
languages for longer code blocks.

It is still possible to enable highlighting on an rst source file basis
using the highlight directive:

.. higlight:: language

and on a literal block basis using the code-block directive:

.. code-block:: language

See http://www.sphinx-doc.org/en/latest/markup/code.html for details.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Cc: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Fix the warning:

WARNING: "latex_documents" config value references unknown document
user/index
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.

As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Python module names should not have hyphens per [PEP 8]. Drop the hyphen
from kernel-doc.py. The extension directive remains unchanged.

[PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-namesReported-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that the files at Documentation/development-process/
were converted to ReST, make create a book at Sphinx.

As we'll have other books related to the development process,
we'll add it as a sub-book.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Now that the build of PDF output on media got fixed, re-add it
to the Sphinx PDF build.

Partially reverts 3eb6cd68 ('Documentation: exclude
media documentation from pdf generation').
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

We need adjustbox to allow adjusting the size of tables that
are bigger than the line width. There are quite a few of them
at the media books.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

When XeLaTeX is in interactive mode, it complains that
py@noticelength already exists. Rename it and declare it
only once to avoid such messages.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Instead of painting the box with gray, let's use a colored
box. IMHO, that makes easier to warn users about some issue
pointed by the Sphinx. It also matches to what we do already
with the HTML output.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

While the current implementation works well when using as a
paragraph, it doesn't work properly if inside a table. As we
have quite a few such cases, fix the logic to take the column
size into account.

PS.: I took the logic there from the latest version of Sphinx.sty
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a sphinx-extension to customize the sphinx c-domain.  No functional
changes right yet, just the boilerplate code.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This extension will be used by the media books.

The name of the math image extension changed on Sphinx 1.4.x,
according with:
	http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmath

Let's autodetect, to keep building with versions < 1.4.
Suggested-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

As we have big tables, reduce the left/right margins and decrease
the point size to 8pt. Visually, it is still good enough, and
now less tables are too big to be displayed.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

pdflatex doesn't accept using some UTF-8 chars, like
"equal or less than" or "equal or greater than" chars. However,
the media documents use them. So, we need to use XeLaTeX for
conversion, and a font that accepts such characters.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The output for those notes are bad in pdf, as they're not
in a box with a different color. Also, it causes the output
to not build if the note is inside a table.

Change its implementation to avoid the above troubles.

The logic there came from:
	https://stackoverflow.com/questions/606746/how-to-customize-an-existing-latex-environment-without-interfering-with-other-enSigned-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Portrait is too small for some tables used at the media docs.
So, allow documents to tell Sphinx to generate some pages
in landscape by using:

.. raw:: latex

    \begin{landscape}

<some stuff>

.. raw:: latex

    \end{landscape}
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The usage of rst2pdf was replaced by pdflatex on a previous
patch. Remove the left-over code at conf.py.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.

* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF

Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::

  make SPHINXDIRS="media gpu" htmldocs

To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::

  make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs

With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Although pdflatex is more robust than rst2pdf, building media
documentation pdf still fails. Exclude media documentation from pdf
generation for now.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>
Acked-by: NMarkus Heiser <markus.heiser@darmarit.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This should eliminate a whole class of markup warnings, at the cost of
occasionally amusing markup choices; we'll have to see if it works out.
Suggested-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This reverts commit 47d6d752.

Commit f42ddca7 (doc-rst: kernel-doc directive, fix state machine
reporter) from Marcus Heiser provides a better fix, so this configuration
change is no longer needed.

Unfortunately warnings generated after parsing in sphinx can end up
with entirely bogus files and line numbers as sources. Strangely for
outright errors this is not a problem. Trying to convert warnings to
errors also doesn't fix it.

The only way to get useful output out of sphinx to be able to root
cause the error seems to be enabling keep_warnings, which inserts
a System Message into the actual output. Not pretty at all, but I
don't really want to fix up core rst/sphinx code, and this gets the job
done meanwhile.

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The rst2pdf tool is a very broken toolchain, with is not capable
of parsing complex documents. As such, it doesn't build the
media book, failing with:

	[ERROR] pdfbuilder.py:130 too many values to unpack

(using rst2pdf version 0.93.dev-r0 and Sphinx version 1.4.5)

So, make it build only the books we know that are safe to build.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

--

Btw, with the standard Sphinx version shipped on Fedora 24 (Sphinx
1.3.1), rst2pdf doesn't build even the simple kernel-documentation,
failing with this error:
    writing Kernel... [ERROR] pdfbuilder.py:130 list index out of range

This is a known bug:
    https://github.com/sphinx-doc/sphinx/issues/1844

So, maybe we should just disable pdf generation from RST for good,
as I suspect that maintaining it with a broken toolchain will be a
big headache.

To honor the:

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

* activate kernel-include directive
* export BUILDDIR=$(BUILDDIR)
* linux_tv: replace '.. include::' with '.. kernel-include:: $BUILDDIR/<foo.h.rst>'
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Implements the minimal boilerplate for Sphinx HTML theme customization.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Implements the reST flat-table directive.

The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:

* column-span: with the role ``cspan`` a cell can be extended through
  additional columns

* row-span: with the role ``rspan`` a cell can be extended through
  additional rows

* auto span rightmost cell of a table row over the missing cells on the right
  side of that table-row.  With Option ``:fill-cells:`` this behavior can
  changed from *auto span* to *auto fill*, which automaticly inserts (empty)

list tables

  The *list tables* formats are double stage lists. Compared to the
  ASCII-art they migth be less comfortable for readers of the
  text-files. Their advantage is, that they are easy to create/modify
  and that the diff of a modification is much more meaningfull, because
  it is limited to the modified content.

The initial implementation was taken from the sphkerneldoc project [1]

[1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.pySigned-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
[jc: fixed typos and misspellings in the docs]
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Read the version and release from the top level Makefile (for use when
Sphinx is invoked directly, by e.g. Read the Docs), but override them
via Sphinx command line arguments in a normal documentation build.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Tell Sphinx where to find the extension, and pass on the kernel src tree
and kernel-doc paths to the extension.

With this, any .rst files under Documentation may contain the kernel-doc
rst directive to include kernel-doc documentation from any source file.

While building, it may be handy to pass kernel-doc extension
configuration on the command line. For example, 'make SPHINXOPTS="-D
kerneldoc_verbosity=0" htmldocs' silences all stderr output from
kernel-doc when the kernel-doc exit code is 0. (The stderr will be
logged unconditionally when the exit code is non-zero.)
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Add basic configuration and makefile to build documentation from any
.rst files under Documentation using Sphinx. For starters, there's just
the placeholder index.rst.

At the top level Makefile, hook Sphinx documentation targets alongside
(but independent of) the DocBook toolchain, having both be run on the
various 'make *docs' targets.

All Sphinx processing is placed into Documentation/Makefile.sphinx. Both
that and the Documentation/DocBook/Makefile are now expected to handle
all the documentation targets, explicitly ignoring them if they're not
relevant for that particular toolchain. The changes to the existing
DocBook Makefile are kept minimal.

There is graceful handling of missing Sphinx and rst2pdf (which is
needed for pdf output) by checking for the tool and python module,
respectively, with informative messages to the user.

If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but
otherwise gracefully fall back to the Sphinx default theme, with an
informative message to the user, and slightly less pretty HTML output.

Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available),
epubdocs and xmldocs targets. The output documents are written into per
output type subdirectories under Documentation/output.

Finally, you can pass options to sphinx-build using the SPHINXBUILD make
variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose
output from Sphinx.

This is based on the original work by Jonathan Corbet, but he probably
wouldn't recognize this as his own anymore.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>