linux.git/Documentation/conf.py, branch v4.8

docs: Set the Sphinx default highlight language to "guess"

2016-08-12T20:11:12+00:00

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: Markus Heiser 
Signed-off-by: Jonathan Corbet

doc-rst: Fix compilation of the pdf docbook

2016-07-15T10:56:10+00:00

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: Mauro Carvalho Chehab 

--

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.

doc-rst: linux_tv/Makefile: Honor quiet make O=dir

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

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

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

doc-rst: boilerplate HTML theme customization

2016-07-05T17:38:49+00:00

Implements the minimal boilerplate for Sphinx HTML theme customization.

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

doc-rst: flat-table directive - initial implementation

2016-06-30T18:58:33+00:00

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.py

Signed-off-by: Markus Heiser 
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet

Documentation/sphinx: set version and release properly

2016-05-30T10:38:53+00:00

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: Jani Nikula

Documentation/sphinx: configure the kernel-doc extension

2016-05-30T10:38:52+00:00

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: Jani Nikula

Documentation/sphinx: add basic working Sphinx configuration and build

2016-05-30T10:38:51+00:00

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: Jani Nikula