linux-toradex.git/Documentation/doc-guide/sphinx.rst, branch v4.16-rc4

sphinx.rst: Allow Sphinx version 1.6 at the docs

2017-08-26T21:50:27+00:00

Now that the PDF building issues with Sphinx 1.6 got fixed,
update the documentation and scripts accordingly.

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

sphinx.rst: document scripts/sphinx-pre-install script

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

Now that we have a script to check for Sphinx dependencies,
document it.

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

sphinx.rst: better organize the documentation about PDF build

2017-07-17T19:18:42+00:00

Instead of having it on just one note, add a separate section.

This way, we could later improve it, providing a better
guide about the needed steps for PDF builds.

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

sphinx.rst: describe the install requirements for kfigure

2017-07-17T19:18:36+00:00

As we now have a document describing the install
requirements for Sphinx, add there the need for GraphViz
and ImageMagick.

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

sphinx.rst: fix unknown reference

2017-07-17T19:18:30+00:00

There's no "Sphinx C Domain" reference at the Kernel
documentation. So, don't use references for it.

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

sphinx.rst: explain the usage of virtual environment

2017-07-17T19:18:24+00:00

As the Sphinx build seems very fragile, specially for
PDF output, add a notice about how to use it on a virtual
environment.

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

docs-rst: move Sphinx install instructions to sphinx.rst

2017-07-17T19:18:18+00:00

The toolchain used by Sphinx is somewhat complex, and installing
it should be part of the doc-guide.

Move it out of changes.rst.

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

docs: update old references for DocBook from the documentation

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

DocBook is mentioned several times at the documentation. Update
the obsolete references from it at the DocBook.

Acked-by: SeongJae Park 
Signed-off-by: Mauro Carvalho Chehab

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

doc: Explain light-handed markup preference a bit better

2017-03-09T09:44:44+00:00

We're still pretty far away from anything like a consensus, but
there's clearly a lot of people who prefer an as-light as possible
approach to converting existing .txt files to .rst. Make sure this is
properly taken into account and clear.

Motivated by discussions with Peter and Christoph and others.

Cc: Christoph Hellwig 
Cc: Peter Zijlstra 
Cc: Jani Nikula 
Cc: Mauro Carvalho Chehab 
Signed-off-by: Daniel Vetter 
Signed-off-by: Jonathan Corbet