Commit Graph

75 Commits

Author SHA1 Message Date
Jonathan Corbet
8d8f60c5e0 Merge branch 'doc/4.9' into docs-next 2016-08-22 15:40:38 -06:00
Mauro Carvalho Chehab
ca7bfe2c8d docs-rst: add package adjustbox
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:36:15 -06:00
Mauro Carvalho Chehab
ba1377fba7 docs-rst: Fix an warning when in interactive mode
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:35:04 -06:00
Mauro Carvalho Chehab
41cff161fe docs-rst: Use better colors for note/warning/attention boxes
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:34:48 -06:00
Mauro Carvalho Chehab
aa4e37a3d1 docs-rst: conf.py: adjust the size of .. note:: tag
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:26:57 -06:00
Markus Heiser
e8f5c617f2 doc-rst: add boilerplate to customize c-domain
Add a sphinx-extension to customize the sphinx c-domain.  No functional
changes right yet, just the boilerplate code.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-22 15:19:15 -06:00
Jonathan Corbet
5dc6911f16 Merge branch 'doc/4.9' into docs-next 2016-08-18 17:22:10 -06:00
Mauro Carvalho Chehab
d4fe7e14e4 docs-rst: enable the Sphinx math extension
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: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:42:33 -06:00
Mauro Carvalho Chehab
85c21e5c3e docs-rst: better adjust margins and font size
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:42:02 -06:00
Mauro Carvalho Chehab
a682ec4ba1 docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:41:52 -06:00
Mauro Carvalho Chehab
6045977465 docs-rst: improve output for .. notes:: on LaTeX
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-en

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:41:42 -06:00
Mauro Carvalho Chehab
caee5cdede docs-rst: allow generating some LaTeX pages in landscape
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:41:37 -06:00
Mauro Carvalho Chehab
a69ab10869 docs-rst: remove a rst2pdf left over code
The usage of rst2pdf was replaced by pdflatex on a previous
patch. Remove the left-over code at conf.py.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-18 16:41:31 -06:00
Jonathan Corbet
cc935bb596 Merge branch 'doc/4.9' into docs-next 2016-08-14 13:57:55 -06:00
Markus Heiser
606b9ac81a doc-rst: generic way to build only sphinx sub-folders
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: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-14 11:51:51 -06:00
Jonathan Corbet
34df2a45bd Merge branch 'doc/4.8-fixes' into docs-next 2016-08-12 17:13:33 -06:00
Jani Nikula
3eb6cd6834 Documentation: exclude media documentation from pdf generation
Although pdflatex is more robust than rst2pdf, building media
documentation pdf still fails. Exclude media documentation from pdf
generation for now.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-12 15:25:53 -06:00
Jonathan Corbet
a7a0729c45 docs: Set the Sphinx default highlight language to "guess"
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 <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-12 14:11:12 -06:00
Mauro Carvalho Chehab
520a247760 doc-rst: Fix compilation of the pdf docbook
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 <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.
2016-07-15 07:56:10 -03:00
Markus Heiser
627e32df1a doc-rst: linux_tv/Makefile: Honor quiet make O=dir
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: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-08 09:31:05 -03:00
Markus Heiser
bc21467114 doc-rst: boilerplate HTML theme customization
Implements the minimal boilerplate for Sphinx HTML theme customization.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-05 14:38:49 -03:00
Markus Heiser
0249a76448 doc-rst: flat-table directive - initial implementation
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 <markus.heiser@darmarIT.de>
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-06-30 12:58:33 -06:00
Jani Nikula
c13ce448c8 Documentation/sphinx: set version and release properly
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 <jani.nikula@intel.com>
2016-05-30 13:38:53 +03:00
Jani Nikula
24dcdeb28b Documentation/sphinx: configure the kernel-doc extension
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 <jani.nikula@intel.com>
2016-05-30 13:38:52 +03:00
Jani Nikula
22cba31bae Documentation/sphinx: add basic working Sphinx configuration and build
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 <jani.nikula@intel.com>
2016-05-30 13:38:51 +03:00