linux-stable.git/Documentation/sphinx, branch v4.12.2

tmplcvt: make the tool more robust

2017-04-11T20:35:15+00:00

Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.

Also, be sure that both parameters are specified.

That should avoid troubles like this:

$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

Use sphinx.version_info directly instead of parsing

2017-03-31T15:19:37+00:00

Using the development version of sphinx caused the parsing of the
version to fail.

Signed-off-by: Rémy Léone 
Signed-off-by: Jonathan Corbet

docs-rst: automatically convert Graphviz and SVG images

2017-03-09T09:59:26+00:00

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 
Cc: Laurent Pinchart 
Tested-by: Mauro Carvalho Chehab 
Tested-by: Daniel Vetter 
Signed-off-by: Daniel Vetter  (v2 - v5)
Signed-off-by: Markus Heiser  (v1, v6)
Signed-off-by: Jonathan Corbet

docs: sphinx-extensions: make rstFlatTable work with docutils 0.13

2016-12-18T20:30:29+00:00

In docutils 0.13, the return type of get_column_widths method of the
Table directive has changed [1], which breaks our flat-table directive
and leads to a TypeError when trying to build the docs [2].

This patch adds support for the new return type, while keeping support
for older docutils versions too.

[1] https://sourceforge.net/p/docutils/patches/120/
[2] https://sourceforge.net/p/docutils/bugs/303/

Signed-off-by: Dmitry Shachnev 
Cc:  # 4.8.x-
Signed-off-by: Jonathan Corbet

docs-rst: parse-headers.pl: cleanup the documentation

2016-12-01T00:08:09+00:00

Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

parse-headers.pl: add documentation for this script

2016-11-19T17:22:08+00:00

Provide a man page for parse-headers.pl, describing
how to use it.

The documentation on ReST format was generated via pod2rst:
	http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet

Documentation/sphinx: rename kernel-doc.py to kerneldoc.py

2016-10-19T22:02:00+00:00

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 
Signed-off-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

Merge tag 'docs-next' of git://git.lwn.net/linux.git into patchwork

2016-09-19T19:36:41+00:00

Merge back from docs-next in order to get the cdomain extension.

With such extension, the number of warnings when building docs
in nitpick mode reduced from 22 to 2 warnings.

* docs-next/docs-next:
  docs/driver-model: fix typo
  DMA-API-HOWTO:  is no more
  doc-rst:c-domain: function-like macros arguments
  doc-rst:c-domain: fix sphinx version incompatibility
  Documentation/filesystems: Fixed typo
  docs: Don't format internal MPT docs
  docs: split up serial-interfaces.rst
  docs: Pull the HSI documentation together
  docs: Special-case function-pointer parameters in kernel-doc
  docs: make kernel-doc handle varargs properly
  x86: fix memory ranges in mm documentation
  documentation/scsi: Remove nodisconnect parameter
  doc: ioctl: Add some clarifications to botching-up-ioctls
  docs: split up the driver book
  Docs: sphinxify device-drivers.tmpl

doc-rst:c-domain: function-like macros arguments

2016-09-16T15:53:40+00:00

Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.

Signed-off-by: Markus Heiser 
Signed-off-by: Jonathan Corbet

doc-rst:c-domain: fix sphinx version incompatibility

2016-09-16T15:53:23+00:00

The self.indexnode's tuple has changed in sphinx version 1.4, from a
former 4 element tuple to a 5 element tuple.

https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c

Signed-off-by: Markus Heiser 
Signed-off-by: Jonathan Corbet