From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
"Jonathan Corbet" <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Mauro Carvalho Chehab <mchehab@kernel.org>,
Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
ksummit-discuss@lists.linuxfoundation.org
Subject: [Ksummit-discuss] [PATCH v2 2/2] docs-rst: add documentation about how to insert images
Date: Mon, 21 Nov 2016 17:27:04 -0200 [thread overview]
Message-ID: <923b7099f6dbf193f5b13e15c6d303e8ef073538.1479756387.git.mchehab@s-opensource.com> (raw)
In-Reply-To: <4d2770fcc7a65dd1ad05387317bc1fb5c4b879be.1479756387.git.mchehab@s-opensource.com>
In-Reply-To: <4d2770fcc7a65dd1ad05387317bc1fb5c4b879be.1479756387.git.mchehab@s-opensource.com>
Inserting images with Sphinx is tricky, due to its limited
image support. So, the Kernel building system needs to
provide some help for it to work.
Document how to do it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
v2: Add the text fixes proposed by Daniel Vetter.
Documentation/doc-guide/images.rst | 81 ++++++++++++++++++++++++++++++++++++++
Documentation/doc-guide/index.rst | 1 +
2 files changed, 82 insertions(+)
create mode 100644 Documentation/doc-guide/images.rst
diff --git a/Documentation/doc-guide/images.rst b/Documentation/doc-guide/images.rst
new file mode 100644
index 000000000000..87516248f7c2
--- /dev/null
+++ b/Documentation/doc-guide/images.rst
@@ -0,0 +1,81 @@
+Inserting images
+================
+
+The Kernel documentation new build system is prepared for two types of
+images: `Graphviz <http://www.graphviz.org/>`__ (``*.dot``) diagrams
+and Scalable Vector Graphics (``*.svg``). While Sphinx also supports a few
+bitmap formats, please don't use it, as it may not work on all output formats.
+
+If you want to add an image on either Graphviz or SVG format, you should
+use Sphinx ``figure``, where the name of the image file should end with
+``.*``, like::
+
+ .. figure:: pipeline.*
+ :alt: pipeline.pdf / pipeline.svg
+ :align: center
+
+ Image Format Negotiation on Pipelines
+
+Using ``.*`` makes Sphinx to look at the right image extension for
+the actual image file, which is converted by the building system.
+
+Scalable Vector Graphics images
+-------------------------------
+
+Sphinx has support for SVG only for html and epub outputs. For LaTeX
+and PDF, the images need to be converted to PDF. The Kernel build
+system does the needed conversion. For that to happen, you need to
+add a ``Makefile`` at the ``Documentation`` subdirectory, and include it
+at ``Documentation/Makefile.sphinx``.
+
+For example, if you want to add ``foo.svg`` image inside a ``bar`` directory,
+you should create a ``bar/Makefile`` directory with::
+
+ IMAGES += bar/foo.svg
+
+Please notice that the path for the file should be relative to the
+``Documentation/`` directory. For the Makefile to be parsed, it should
+be included at the ``Documentation/Makefile.sphinx`` file with::
+
+ include Documentation/bar/Makefile
+
+Please notice that the path for the file should be relative to the
+kernel's root directory.
+
+With that, when generating either a LaTeX or PDF output, the build
+system will automatically convert the image output to ``*.pdf``::
+
+ GENPDF Documentation/bar/foo.svg
+
+Graphviz diagrams
+-----------------
+
+Sphinx doesn't support Graphviz directly. So, the Kernel building system
+has to convert it first to Scalable Vector Graphics, before calling
+Sphinx to handle the diagram. Also, for LaTeX and PDF, the image also
+needs to be converted to PDF. For that to happen, you need to add a
+``Makefile`` at the ``Documentation`` subdirectory, and include it at
+``Documentation/Makefile.sphinx``.
+
+For example, if you want to add ``foobar.dot`` image inside a ``bar``
+directory, you should create a ``bar/Makefile`` directory with::
+
+ DOTS += bar/foobar.svg
+
+Please notice that the path for the file should be relative to the
+``Documentation/`` directory. For the Makefile to be parsed, it should
+be included at the ``Documentation/Makefile.sphinx`` file with::
+
+ include Documentation/bar/Makefile
+
+Please notice that the path for the file should be relative to the
+kernel's root directory.
+
+With that, before calling Sphinx, the Kernel's build system will generate
+a SVG file using Graphviz::
+
+ DOT Documentation/bar/foobar.dot
+
+And, if the output is either LaTeX or PDF, it will also convert it to PDF::
+
+ GENPDF Documentation/bar/foobar.svg
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 6fff4024606e..a7080d44105c 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -8,6 +8,7 @@ How to write kernel documentation
:maxdepth: 1
sphinx.rst
+ images.rst
kernel-doc.rst
parse-headers.rst
docbook.rst
--
2.9.3
prev parent reply other threads:[~2016-11-21 19:27 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-11-21 19:27 [Ksummit-discuss] [PATCH v2 1/2] docs-rst: move the rules for svg and graphviz to Makefile.sphinx Mauro Carvalho Chehab
2016-11-21 19:27 ` Mauro Carvalho Chehab [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=923b7099f6dbf193f5b13e15c6d303e8ef073538.1479756387.git.mchehab@s-opensource.com \
--to=mchehab@s-opensource.com \
--cc=corbet@lwn.net \
--cc=ksummit-discuss@lists.linuxfoundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).