Commit 85c21e5c3e (docs-rst: better adjust margins and font size) added a
\usepackage{geometry} that conflicts with another inclusion deep within the
dependencies with newer versions of Sphinx, causing the the PDF build to fail
with a "conflicting parameters" error.
Detect the Sphinx version, using sphinxsetup for Sphinx versions 1.5 and
upper.
Fixes: 85c21e5c3e
[jc: Tweaked logic to exclude 1.5.x for x < 3 ]
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Otherwise we get PDF build failures when LaTeX refused to acknowledge the
existence of \ifthenelse
Fixes: 41cff161fe
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The userspace API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The sound subsystem book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The dev-tools API book was added without the bits required to
generate PDF output at the main conf.py. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
The crypto API book was added without the bits required to
generate PDF output. Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
There's no kernel-documentation.rst file at Documentation/
anymore. So, remove it from the list of LaTeX-generated
documents.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
As we add more documents, it makes more sense to sort the
entries there in alphabetical order, as it makes easier to
check if something is not there.
Signed-off-by: Mauro 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Pull input subsystem updates from Dmitry Torokhov:
- a big update from Mauro converting input documentation to ReST format
- Synaptics PS/2 is now aware of SMBus companion devices, which means
that we can now use native RMI4 protocol to handle touchpads, instead
of relying on legacy PS/2 mode.
- we removed support from BMA180 accelerometer from input devices as it
is now handled properly by IIO
- update to TSC2007 to corretcly report pressure
- other miscellaneous driver fixes.
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (152 commits)
Input: ar1021_i2c - use BIT to check for a bit
Input: twl4030-pwrbutton - use input_set_capability() helper
Input: twl4030-pwrbutton - use correct device for irq request
Input: ar1021_i2c - enable touch mode during open
Input: add uinput documentation
dt-bindings: input: add bindings document for ar1021_i2c driver
dt-bindings: input: rotary-encoder: fix typo
Input: xen-kbdfront - add module parameter for setting resolution
ARM: pxa/raumfeld: fix compile error in rotary controller resources
Input: xpad - do not suggest writing to Dominic
Input: xpad - don't use literal blocks inside footnotes
Input: xpad - note that usb/devices is now at /sys/kernel/debug/
Input: docs - freshen up introduction
Input: docs - split input docs into kernel- and user-facing
Input: docs - note that MT-A protocol is obsolete
Input: docs - update joystick documentation a bit
Input: docs - remove disclaimer/GPL notice
Input: fix "Game console" heading level in joystick documentation
Input: rotary-encoder - remove references to platform data from docs
Input: move documentation for Amiga CD32
...
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>
Using the development version of sphinx caused the parsing of the
version to fail.
Signed-off-by: Rémy Léone <remy.leone@gmail.com>
Signed-off-by: Jonathan 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: John Keeping <john@metanate.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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>
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>
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: Jani 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: Mauro 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: Mauro 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-names
Reported-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJX/QbjAAoJEAhfPr2O5OEVDKkP/30o73ZhzBkDR3xgApbmVdrw
1NQYZq8UKibZ87hv949535N3lwaHFV0mA8ylheu2MMArd1GoZvyXKqNbJN9316kQ
mSI8wVK77UiBP7RRolEepCuliQExNmayUm+kNZEZsF67+flilkcumCBqlPf114Sl
ruhpGTSAIz2mgbxGsPkFiN+4xl2AZFOjiiHsp9doBE8HAtEp3PyCrPv5T6zkK7PQ
KKf7ribcIB65tx0zBmhkfJOef/mqK/t7XgQS7kVRB3G4zr1nkh4g2iw/QbUreBtE
94p1VYAMBFfpCNe1rWaaBOxYRLsDBMQHz2LvOvj8HZKrsuBCKQQ4jAoYQ4bNi8cu
nWAb5Z19npoxJRYCGrPs8MJtCFD1IoT4zjiA8Ld5BT4SqBsCQ6VrgiUpQESzjtlj
Xp7V1D2ak3vx40FAuDGZsb7JwGTuIrK18rZyKSjvHbnydWiJlaHY9kR3lOe91wc2
MZOiD3K4lM5Lvse07nLVgOTjXW1fC3ScliRCQVLU/Wbm6A8UKiejES8sy0bFk9sU
8Go3RaAPVeQLGFLqOJG+6yu7sJ1FCZzAthKbpxtY8p/iKZE4QO0n4Y6Q2NjcjHJt
lDKYp83jne+AMthbLR+Ab6IL2GoOxaW6fnTrDioDxGc9Cvba90xYsZCIxbcGrM4h
cu1bOLUp5Ei1wHvaqRla
=JqCR
-----END PGP SIGNATURE-----
Merge tag 'media/v4.9-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab:
- Documentation improvements: conversion of all non-DocBook documents
to Sphinx and lots of fixes to the uAPI media book
- New PCI driver for Techwell TW5864 media grabber boards
- New SoC driver for ATMEL Image Sensor Controller
- Removal of some obsolete SoC drivers (s5p-tv driver and soc_camera
drivers)
- Addition of ST CEC driver
- Lots of drivers fixes, improvements and additions
* tag 'media/v4.9-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (464 commits)
[media] ttusb_dec: avoid the risk of go past buffer
[media] cx23885: Fix some smatch warnings
[media] si2165: switch to regmap
[media] si2165: use i2c_client->dev instead of i2c_adapter->dev for logging
[media] si2165: Remove legacy attach
[media] cx231xx: attach si2165 driver via i2c_client
[media] cx231xx: Prepare for attaching new style i2c_client DVB demod drivers
[media] cx23885: attach si2165 driver via i2c_client
[media] si2165: support i2c_client attach
[media] si2165: avoid division by zero
[media] rcar-vin: add R-Car gen2 fallback compatibility string
[media] lgdt3306a: remove 20*50 msec unnecessary timeout
[media] cx25821: Remove deprecated create_singlethread_workqueue
[media] cx25821: Drop Freeing of Workqueue
[media] cxd2841er: force 8MHz bandwidth for DVB-C if specified bw not supported
[media] redrat3: hardware-specific parameters
[media] redrat3: remove hw_timeout member
[media] cxd2841er: BER and SNR reading for ISDB-T
[media] dvb-usb: avoid link error with dib3000m{b,c|
[media] dvb-usb: split out common parts of dibusb
...
The Sphinx transition is still creating a fair amount of work. Here we
have a number of fixes and, importantly, a proper PDF output solution,
thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.
I've started a couple of new books: a driver API book (based on the old
device-drivers.tmpl) and a development tools book. Both are meant to show
how we can integrate together our existing documentation into a more
coherent and accessible whole. It involves moving some stuff around and
formatting changes, but, I think, the results are worth it. The good news
is that most of our existing Documentation/*.txt files are *almost* in RST
format already; the amount of messing around required is minimal.
And, of course, there's the usual set of updates, typo fixes, and more.
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJX8st8AAoJEI3ONVYwIuV6d10P/0Zsnx3hSSx22aHxP4kVb4s/
NTttFAienYzc2fYYD3K/wMQbSbprW8Pp7uSP1suzAbU5FGgfLyDFQHnE0AVqFNiT
MHVc5oBWp4ZlvNcyQUeXOsKtb5Rin00XHjer2mm/T9HfgmCYR4i+C9HQuv+J94Jf
sgeI4IimvLjlp7dDbhcIfdqCpZ+UwBSpSm9w5f7astYDjocJHrkBqyk/46Ir4qz9
+2joNZRWMUatrQYJWMJnnvlnx8lHhkDjaL/Egy+f7ucpddEkbGvWvabGCSMtCyzS
CKlA53Y4wS59cNFkAuxsHjun4TcQhbZn/iBIM+8aOdameO0ksC4jSoND2P6N6vKF
dHkAkayP9ChW3k/J8D+3cGIJNFiaYevEXcgxLyShjCuh4t4yfOC9aIGUl3Ye9/mR
tiKpMsvzmwJ+yO+kzJsxWTmRAX5wdI1Z062ltiS1dmSbl3c3NgQFpfP7V7AJSQ7c
DzkuoUnGEqJOHm64dAZQuxL4jj6StzejjxlhH0bIjbNn1a9VlX9afwsdJaXA+kmr
jQHJtR0wD1mLMYYdvNEiqvcCbumG+kaXmH6eUQadRxruRdZyhi1Z6Ql1CtwQGtbR
SetC/MVxIN3fGPbZYhJ162xVjQ8OeX0ndRmRjy6SBDMoRGSKqi2IME8JAGOshxE0
0uYAJJFZOeiR6KaPnci/
=kGKl
-----END PGP SIGNATURE-----
Merge tag 'docs-4.9' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet:
"This is the documentation update pull for the 4.9 merge window.
The Sphinx transition is still creating a fair amount of work. Here we
have a number of fixes and, importantly, a proper PDF output solution,
thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.
I've started a couple of new books: a driver API book (based on the
old device-drivers.tmpl) and a development tools book. Both are meant
to show how we can integrate together our existing documentation into
a more coherent and accessible whole. It involves moving some stuff
around and formatting changes, but, I think, the results are worth it.
The good news is that most of our existing Documentation/*.txt files
are *almost* in RST format already; the amount of messing around
required is minimal.
And, of course, there's the usual set of updates, typo fixes, and
more"
* tag 'docs-4.9' of git://git.lwn.net/linux: (120 commits)
URL changed for Linux Foundation TAB
dax : Fix documentation with respect to struct pages
iio: Documentation: Correct the path used to create triggers.
docs: Remove space-before-label guidance from CodingStyle
docs-rst: add inter-document cross references
Documentation/email-clients.txt: convert it to ReST markup
Documentation/kernel-docs.txt: reorder based on timestamp
Documentation/kernel-docs.txt: Add dates for online docs
Documentation/kernel-docs.txt: get rid of broken docs
Documentation/kernel-docs.txt: move in-kernel docs
Documentation/kernel-docs.txt: remove more legacy references
Documentation/kernel-docs.txt: add two published books
Documentation/kernel-docs.txt: sort books per publication date
Documentation/kernel-docs.txt: adjust LDD references
Documentation/kernel-docs.txt: some improvements on the ReST output
Documentation/kernel-docs.txt: Consistent indenting: 4 spaces
Documentation/kernel-docs.txt: Add 4 paper/book references
Documentation/kernel-docs.txt: Improve layouting of book list
Documentation/kernel-docs.txt: Remove offline or outdated entries
docs: Clean up bare :: lines
...
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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 3eb6cd6834 ('Documentation: exclude
media documentation from pdf generation').
Signed-off-by: Mauro 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Markus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: Jonathan 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: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan 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: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan 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: Jani Nikula <jani.nikula@intel.com>
Acked-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan 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: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan 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: 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.
Mauro Carvalho Chehab