Commit Graph

75 Commits

Author SHA1 Message Date
Mauro Carvalho Chehab
e0de2b59e2 docs: conf.py: only use CJK if the font is available
If we try to build a book with asian characters with XeLaTeX
and the font is not available, it will produce an error.

So, instead, add a logic at conf.py to detect if the proper
font is installed.

This will avoid an error while building the document, although
the result may not be readable.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:51 -03:00
Mauro Carvalho Chehab
24889dad3d docs: conf.py: add CJK package needed by translations
In order to be able to output Asian symbols with XeLaTeX, we
need the xeCJK package, and a default font for CJK symbols.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:51 -03:00
Mauro Carvalho Chehab
9d42afbe6b docs: pdf: add all Documentation/*/index.rst to PDF output
Currently, all index files should be manually added to the
latex_documents array at conf.py.

While this allows fine-tuning some LaTeX specific things, like
the name of the output file and the name of the document, it
is not uncommon to forget adding new documents there.

So, add a logic that will seek for all Documentation/*/index.rst.
If the index is not yet at latex_documents, it includes using
a reasonable default.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2019-07-17 06:57:51 -03:00
Stephen Kitt
7282a93f4d Disable Sphinx SmartyPants in HTML output
The handling of dashes in particular results in confusing
documentation in a number of instances, since "--" becomes an
en-dash. This disables SmartyPants wholesale, losing smart quotes
along with smart dashes.

With Sphinx 1.6 we could fine-tune the conversion, using the new
smartquotes and smartquotes_action settings.

Signed-off-by: Stephen Kitt <steve@sk2.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-30 15:30:34 -06:00
Jonathan Corbet
d74b0d31dd Docs: An initial automarkup extension for sphinx
Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-06-26 11:14:09 -06:00
Jonathan Corbet
3bc8088464 docs: Fix conf.py for Sphinx 2.0
Our version check in Documentation/conf.py never envisioned a world where
Sphinx moved beyond 1.x.  Now that the unthinkable has happened, fix our
version check to handle higher version numbers correctly.

Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-05-24 09:09:32 -06:00
Linus Torvalds
01aa9d518e This is a fairly typical cycle for documentation. There's some welcome
readability improvements for the formatted output, some LICENSES updates
 including the addition of the ISC license, the removal of the unloved and
 unmaintained 00-INDEX files, the deprecated APIs document from Kees, more
 MM docs from Mike Rapoport, and the usual pile of typo fixes and
 corrections.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJbztcuAAoJEI3ONVYwIuV6nTAP/0Be+5dNPGJmSnb/RbkwBuBV
 zAFVUj2sx4lZlRmWRZ0r7AOef2eSw3IvwBix/vnmllYCVahjp+BdRbhXQAijjyeb
 FWWjOH50/J+BaxSthAINiLRLvuoe0D/M08OpmXQfRl5q0S8RufeV3BDtEABx9j2n
 IICPGTl8LpPUgSMA4cw8zPhHdauhZpbmL2mGE9LXZ27SJT4S8lcHMwyPU1n5S+Jd
 ChEz5g9dYr3GNxFp712pkI5GcVL3tP2nfoVwK7EuGf1tvSnEnn2kzac8QgMqorIh
 xB2+Sh4XIUCbHYpGHpxIniD+WI4voNr/E7STQioJK5o2G4HTuxLjktvTezNF8paa
 hgNHWjPQBq0OOCdM/rsffONFF2J/v/r7E3B+kaRg8pE0uZWTFaDMs6MVaL2fL4Ls
 DrFhi90NJI/Fs7uB4sriiviShAhwboiSIRXJi4VlY/5oFJKHFgqes+R7miU+zTX3
 2qv0k4mWZXWDV9w1piPxSCZSdRzaoYSoxEihX+tnYpCyEcYd9ovW/X1Uhl/wCWPl
 Ft+Op6rkHXRXVfZzTLuF6PspZ4Udpw2PUcnA5zj5FRDDBsjSMFR31c19IFbCeiNY
 kbTIcqejJG1WbVrAK4LCcFyVSGxbrr281eth4rE06cYmmsz3kJy1DB6Lhyg/2vI0
 I8K9ZJ99n1RhPJIcburB
 =C0wt
 -----END PGP SIGNATURE-----

Merge tag 'docs-4.20' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "This is a fairly typical cycle for documentation. There's some welcome
  readability improvements for the formatted output, some LICENSES
  updates including the addition of the ISC license, the removal of the
  unloved and unmaintained 00-INDEX files, the deprecated APIs document
  from Kees, more MM docs from Mike Rapoport, and the usual pile of typo
  fixes and corrections"

* tag 'docs-4.20' of git://git.lwn.net/linux: (41 commits)
  docs: Fix typos in histogram.rst
  docs: Introduce deprecated APIs list
  kernel-doc: fix declaration type determination
  doc: fix a typo in adding-syscalls.rst
  docs/admin-guide: memory-hotplug: remove table of contents
  doc: printk-formats: Remove bogus kobject references for device nodes
  Documentation: preempt-locking: Use better example
  dm flakey: Document "error_writes" feature
  docs/completion.txt: Fix a couple of punctuation nits
  LICENSES: Add ISC license text
  LICENSES: Add note to CDDL-1.0 license that it should not be used
  docs/core-api: memory-hotplug: add some details about locking internals
  docs/core-api: rename memory-hotplug-notifier to memory-hotplug
  docs: improve readability for people with poorer eyesight
  yama: clarify ptrace_scope=2 in Yama documentation
  docs/vm: split memory hotplug notifier description to Documentation/core-api
  docs: move memory hotplug description into admin-guide/mm
  doc: Fix acronym "FEKEK" in ecryptfs
  docs: fix some broken documentation references
  iommu: Fix passthrough option documentation
  ...
2018-10-24 18:01:11 +01:00
Darrick J. Wong
44ba0bb4f2 docs: improve readability for people with poorer eyesight
My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation.  Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.

Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.

For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Acked-by: Dave Chinner <dchinner@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-10-07 09:16:50 -06:00
Darrick J. Wong
8a98ec7c7b docs: promote the ext4 data structures book to top level
Move the ext4 data structures book to Documentation/filesystems/ext4/
since the administrative information moved elsewhere.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-05 19:20:08 -04:00
Darrick J. Wong
d309121592 docs: move ext4 administrative docs to admin-guide/
Move the ext4 mount option and other administrative stuff to the Linux
administrator's guide.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-05 19:11:59 -04:00
Darrick J. Wong
e5f0926115 docs: generate a separate ext4 pdf file from the documentation
The documentation build scripts won't build a pdf for the ext4
documentation unless explicitly called for, so ask for a separate
ext4.pdf to be generated with all the documentation.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-10-02 22:40:32 -04:00
Darrick J. Wong
b4becd48b7 ext4: import inode data fork chapter from wiki page
Import the chapter about inode data fork from the on-disk format wiki
page into the kernel documentation.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
Signed-off-by: Theodore Ts'o <tytso@mit.edu>
2018-07-29 15:45:00 -04:00
Jonathan Corbet
2a7c7cba38 docs: Remove "could not extract kernel version" warning
This warning will happen for every normal kernel docs build and doesn't
carry any useful information.  Should anybody actually depend on this
"version" variable (which isn't clear to me), the "unknown version" value
will be clue enough.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-11 15:20:04 -07:00
Mauro Carvalho Chehab
54d6d73f50 docs-rst: don't require adjustbox anymore
Only the media PDF book was requiring adjustbox, in order to
scale big tables. That worked pretty good with Sphinx versions
1.4 and 1.5, but Spinx 1.6 changed the way tables are produced,
by introducing some weird macros before tabulary.
That causes adjustbox to fail. So, it can't be used anymore,
and its usage was removed from the media book.

So, let's remove it from conf.py and sphinx-pre-install.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08 10:02:55 -06:00
Mauro Carvalho Chehab
9fdcd6afd8 docs-rst: conf.py: only setup notice box colors if Sphinx < 1.6
Sphinx 1.5 added a new way to change backward colors for note
boxes, but kept backward compatibility with 1.4. On Sphinx 1.6,
the old way stopped working, in favor of a new less hackish
way.

Unfortunately, this is currently too buggy to be used, and
the old way doesn't work anymore. So, we have no option but
to stick with boring notice boxes.

One example of such bug is the notice that it is inside
struct v4l2_plane, at the "bytesused" field.

At least, add a notice about how to use, as maybe some day
the bug will vanish.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08 10:02:44 -06:00
Mauro Carvalho Chehab
c4b326e1a6 docs-rst: conf.py: remove lscape from LaTeX preamble
Only the media book used this extension in the past, but
it is not required anymore.

Cleanup patch only.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-09-08 10:02:39 -06:00
Mauro Carvalho Chehab
646056ec3b docs-rst: fix verbatim font size on tables
On Sphinx 1.6, fancy boxes are used for verbatim. The sphinx.sty
sets verbatim font is always \small. That causes a problem
inside tables that use smaller fonts, as it can be too big for
the box.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-26 15:50:20 -06:00
Markus Heiser
0e4c2b7589 docs: fix minimal sphinx version in conf.py
according to what Documentation/doc-guide/sphinx.rst says::

  The ReST markups currently used by the Documentation/ files
  are meant to be built with ``Sphinx`` version 1.3 or upper.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-24 13:33:25 -06:00
Mauro Carvalho Chehab
5148e6ab76 docs-rst: pdf: use same vertical margin on all Sphinx versions
Currently, on Sphinx up to version 1.4, pdf output uses a vertical
margin of 1 inch. For upper versions, it uses a margin of 0.5 inches.

That causes both page headers and footers to be very close to the margin
of the sheet. Not all printers support writing like that.

Also, there's no reason why the layout for newer versions would be
different than for previous ones.

So, standardize it, by always setting to 1 inch.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-08-24 13:23:31 -06:00
Mauro Carvalho Chehab
633d612bda Docs: Fix breakage with Sphinx 1.5 and upper
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>
2017-06-23 13:45:37 -06:00
Jonathan Corbet
cc11022191 Docs: Include the Latex "ifthen" package
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>
2017-06-23 13:45:30 -06:00
Mauro Carvalho Chehab
bffac837f3 docs-rst: convert sh book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:18 -03:00
Mauro Carvalho Chehab
05e0f3b996 docs-rst: convert networking book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:13 -03:00
Mauro Carvalho Chehab
90f9f118b7 docs-rst: convert filesystems book to ReST
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:08 -03:00
Mauro Carvalho Chehab
6bb33768db docs-rst: add userspace API book to pdf output
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>
2017-05-16 08:44:07 -03:00
Mauro Carvalho Chehab
f3377977aa docs-rst: add sound book to pdf output
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>
2017-05-16 08:44:07 -03:00
Mauro Carvalho Chehab
81e11d490e docs-rst: add dev-tools book to pdf output
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>
2017-05-16 08:44:06 -03:00
Mauro Carvalho Chehab
8db0b75f42 docs-rst: add crypto API book to pdf output
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>
2017-05-16 08:44:06 -03:00
Mauro Carvalho Chehab
1d8c4e1fde docs-rst: conf.py: remove kernel-documentation from LaTeX
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>
2017-05-16 08:44:06 -03:00
Mauro Carvalho Chehab
c2b563d8a3 docs-rst: conf.py: sort LaTeX documents in alphabetical order
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>
2017-05-16 08:44:05 -03:00
Mauro Carvalho Chehab
2a054b5156 conf.py: define a color for important markup on PDF output
As kdbg.rst uses the ".. important::" annotation, let's define a
color for PDF output.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-05-16 08:44:05 -03:00
Mauro Carvalho Chehab
c4fcd7cabb docs-rst: convert kernel-hacking to ReST
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>
2017-05-16 08:00:49 -03:00
Linus Torvalds
16a12fa9ae Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input
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
  ...
2017-05-03 12:38:20 -07:00
Mauro Carvalho Chehab
e2ba573120 Input: create a book with Linux Input documentation
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>
2017-04-05 15:45:07 -07:00
Rémy Léone
c46988aef2 Use sphinx.version_info directly instead of parsing
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>
2017-03-31 09:19:37 -06:00
Markus Heiser
db6ccf23e8 docs-rst: automatically convert Graphviz and SVG images
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Daniel 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: Jonathan Corbet <corbet@lwn.net>
2017-03-09 02:59:26 -07:00
John Keeping
fd5d666932 Documentation/sphinx: fix primary_domain configuration
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>
2017-03-03 16:12:30 -07:00
Jonathan Corbet
dc36143fba docs: Remove the copyright year from conf.py
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.
2017-02-06 11:52:19 -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
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
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
Jani Nikula
b459106ea4 Documentation/sphinx: set literal block highlight language to none
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>
2016-11-03 12:38:47 +02:00
Jani Nikula
8d26d90ba3 Documentation/sphinx: include admin-guide in the latex/pdf build
Fix the warning:

WARNING: "latex_documents" config value references unknown document
user/index

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
2016-11-03 12:38:25 +02:00
Mauro Carvalho Chehab
9d85025b04 docs-rst: create an user's manual book
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>
2016-10-24 08:12:35 -02:00
Mauro Carvalho Chehab
0e4f07a65f docs: rename development-process/ to process/
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>
2016-10-24 08:12:35 -02:00
Jani Nikula
58af04dff7 Documentation/sphinx: rename kernel-doc.py to kerneldoc.py
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>
2016-10-19 16:02:00 -06:00
Linus Torvalds
de34f4da7f media updates for v4.9-rc1
-----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
  ...
2016-10-11 13:22:22 -07:00
Linus Torvalds
02bafd96f3 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.
 -----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
  ...
2016-10-04 13:54:07 -07:00
Mauro Carvalho Chehab
f0ddda3e94 docs-rst: create a book for the development process
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>
2016-09-20 18:33:46 -06:00
Mauro Carvalho Chehab
0d1c7d60c2 docs-rst: add media documentation to PDF output
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>
2016-08-22 21:25:06 -03:00