linux.git/Documentation/sphinx, branch v4.14

Documentation/sphinx: fix kernel-doc decode for non-utf-8 locale

2017-08-31T19:36:28+00:00

On python3, Popen() universal_newlines=True converts the subprocess
stdout to unicode text using a codec based on user preferences. Given
LANG indicating ascii and utf-8 stdout from the subprocess, you'd get:

WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno
../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't
decode byte 0xe2 in position 6368: ordinal not in range(128)

Fix this by dropping universal_newlines=True and replacing the implicit
LANG specific decode with an explicit utf-8 decode. This also gets rid
of the annoying conditional code for python 2 vs. 3.

Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on python3")
Reference: http://mid.mail-archive.com/54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org
Reported-and-tested-by: Randy Dunlap 
Cc: Jonathan Corbet 
Cc: Mauro Carvalho Chehab 
Signed-off-by: Jani Nikula 
Signed-off-by: Jonathan Corbet

sphinx-pre-install: use a requirements file

2017-07-23T21:51:24+00:00

Instead of using 3 commands to install a virtualenv, use
a single one, reading the requirements from this file:

	Documentation/sphinx/requirements.txt

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

Docs: clean up some DocBook loose ends

2017-06-23T20:17:38+00:00

There were a few bits and pieces left over from the now-disused DocBook
toolchain; git rid of them.

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

docs-rst: get rid of Documentation/sphinx/tmplcvt script

2017-05-16T11:44:24+00:00

As everything was converted to ReST, we don't need this
script anymore.

Signed-off-by: Mauro Carvalho Chehab

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