From patchwork Thu Mar 2 18:06:03 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 9601911 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A855160453 for ; Fri, 3 Mar 2017 01:52:37 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 951C0285A1 for ; Fri, 3 Mar 2017 01:52:37 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 88AC7285CC; Fri, 3 Mar 2017 01:52:37 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 85F59285A1 for ; Fri, 3 Mar 2017 01:52:36 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 891C36EC92; Fri, 3 Mar 2017 01:51:44 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from osg.samsung.com (ec2-52-27-115-49.us-west-2.compute.amazonaws.com [52.27.115.49]) by gabe.freedesktop.org (Postfix) with ESMTP id 79AF26E209 for ; Thu, 2 Mar 2017 18:06:13 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by osg.samsung.com (Postfix) with ESMTP id DF925A0E66; Thu, 2 Mar 2017 18:06:34 +0000 (UTC) X-Virus-Scanned: amavisd-new at osg.samsung.com Received: from osg.samsung.com ([127.0.0.1]) by localhost (s-opensource.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id DEHlRaqjaGhI; Thu, 2 Mar 2017 18:06:31 +0000 (UTC) Received: from vento.lan (177.41.125.80.dynamic.adsl.gvt.net.br [177.41.125.80]) by osg.samsung.com (Postfix) with ESMTPSA id 40D1DA0C73; Thu, 2 Mar 2017 18:06:29 +0000 (UTC) Date: Thu, 2 Mar 2017 15:06:03 -0300 From: Mauro Carvalho Chehab To: Daniel Vetter Subject: Re: [PATCH] docs-rst: automatically convert Graphviz and SVG images Message-ID: <20170302150603.6c97765f@vento.lan> In-Reply-To: <20170302154002.4552-1-daniel.vetter@ffwll.ch> References: <20170302151638.1882-2-daniel.vetter@ffwll.ch> <20170302154002.4552-1-daniel.vetter@ffwll.ch> Organization: Samsung X-Mailer: Claws Mail 3.14.1 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 X-Mailman-Approved-At: Fri, 03 Mar 2017 01:51:38 +0000 Cc: Markus Heiser , Jonathan Corbet , DRI Development , linux-doc@vger.kernel.org, Laurent Pinchart , Daniel Vetter X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP Em Thu, 2 Mar 2017 16:40:02 +0100 Daniel Vetter escreveu: > From: Markus Heiser > > 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**) > > v2: s/DOC/DOT/ in a few places (by Daniel). > > v3: Simplify stuff a bit (by Daniel): > > - Remove path detection and setup/check code for that. In > Documentation/media/Makefile we already simply use these tools, > better to have one consolidated check if we want/need one. Also > remove the convertsvg support, we require ImageMagick's convert > already in the doc build, no need for a 2nd fallback. > > - Use sphinx for depency tracking, remove hand-rolled version. > > - Forward stderr from dot and convert, otherwise debugging issues with > the diagrams is impossible. > > v4: Only sphinx 1.4 (released in Mar 2016) has patches.Figure. > Implement Markus suggestion for backwards compatability with earlier > releases. Laurent reported this, running sphinx 1.3. Solution entirely > untested. > > v5: Use an explicit version check (suggested by Laurent). Tested here with the enclosed patch. It crashed: Exception occurred: File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 222, in dot2format sys.stderr.write(err) TypeError: write() argument must be str, not bytes The full traceback has been saved in /tmp/sphinx-err-_1vahbmg.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at . Thanks! Documentation/Makefile.sphinx:69: recipe for target 'htmldocs' failed make[1]: *** [htmldocs] Error 1 Makefile:1450: recipe for target 'htmldocs' failed make: *** [htmldocs] Error 2 Weird enough, it produced a Documentation/output/media/uapi/v4l/pipeline.svg file. Full trace: Traceback (most recent call last): File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/util/parallel.py", line 73, in _process ret = func(arg) File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/builders/__init__.py", line 380, in write_process self.write_doc(docname, doctree) File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/builders/html.py", line 448, in write_doc self.docwriter.write(doctree, destination) File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/writers/__init__.py", line 80, in write self.translate() File "/home/mchehab/.local/lib/python3.5/site-packages/sphinx/writers/html.py", line 47, in translate self.document.walkabout(visitor) File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 174, in walkabout if child.walkabout(visitor): File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 174, in walkabout if child.walkabout(visitor): File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 174, in walkabout if child.walkabout(visitor): File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 166, in walkabout visitor.dispatch_visit(self) File "/home/mchehab/.local/lib/python3.5/site-packages/docutils/nodes.py", line 1882, in dispatch_visit return method(node) File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 302, in visit_kernel_figure convert_image(img_node, self) File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 193, in convert_image dot2format(src_fname, dst_fname) File "/devel/v4l/patchwork/Documentation/sphinx/kfigure.py", line 222, in dot2format sys.stderr.write(err) TypeError: write() argument must be str, not bytes Thanks, Mauro --- [PATCH] docs-rst: Don't use explicit Makefile rules to build SVG and DOT files Now that we have an extension to handle images, use it. Signed-off-by: Mauro Carvalho Chehab diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile index 32663602ff25..5bd52ea1eff0 100644 --- a/Documentation/media/Makefile +++ b/Documentation/media/Makefile @@ -1,51 +1,6 @@ -# Rules to convert DOT and SVG to Sphinx images - -SRC_DIR=$(srctree)/Documentation/media - -DOTS = \ - uapi/v4l/pipeline.dot \ - -IMAGES = \ - typical_media_device.svg \ - uapi/dvb/dvbstb.svg \ - uapi/v4l/bayer.svg \ - uapi/v4l/constraints.svg \ - uapi/v4l/crop.svg \ - uapi/v4l/fieldseq_bt.svg \ - uapi/v4l/fieldseq_tb.svg \ - uapi/v4l/nv12mt.svg \ - uapi/v4l/nv12mt_example.svg \ - uapi/v4l/pipeline.svg \ - uapi/v4l/selection.svg \ - uapi/v4l/subdev-image-processing-full.svg \ - uapi/v4l/subdev-image-processing-scaling-multi-source.svg \ - uapi/v4l/subdev-image-processing-crop.svg \ - uapi/v4l/vbi_525.svg \ - uapi/v4l/vbi_625.svg \ - uapi/v4l/vbi_hsync.svg \ - -DOTTGT := $(patsubst %.dot,%.svg,$(DOTS)) -IMGDOT := $(patsubst %,$(SRC_DIR)/%,$(DOTTGT)) - -IMGTGT := $(patsubst %.svg,%.pdf,$(IMAGES)) -IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT)) - -cmd = $(echo-cmd) $(cmd_$(1)) - -quiet_cmd_genpdf = GENPDF $2 - cmd_genpdf = convert $2 $3 - -quiet_cmd_gendot = DOT $2 - cmd_gendot = dot -Tsvg $2 > $3 - -%.pdf: %.svg - @$(call cmd,genpdf,$<,$@) - -%.svg: %.dot - @$(call cmd,gendot,$<,$@) - # Rules to convert a .h file to inline RST documentation +SRC_DIR=$(srctree)/Documentation/media PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl UAPI = $(srctree)/include/uapi/linux KAPI = $(srctree)/include/linux diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst index 8f7490c9a8ef..5562fba1d51d 100644 --- a/Documentation/media/intro.rst +++ b/Documentation/media/intro.rst @@ -13,8 +13,8 @@ A typical media device hardware is shown at :ref:`typical_media_device`. .. _typical_media_device: -.. figure:: typical_media_device.* - :alt: typical_media_device.pdf / typical_media_device.svg +.. kernel-figure:: typical_media_device.svg + :alt: typical_media_device.svg :align: center Typical Media Device diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst index 2ed5c23102b4..0e76067a5b58 100644 --- a/Documentation/media/uapi/dvb/intro.rst +++ b/Documentation/media/uapi/dvb/intro.rst @@ -55,8 +55,8 @@ Overview .. _stb_components: -.. figure:: dvbstb.* - :alt: dvbstb.pdf / dvbstb.svg +.. kernel-figure:: dvbstb.svg + :alt: dvbstb.svg :align: center Components of a DVB card/STB diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index be58894c9c89..adea29b14135 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -53,8 +53,8 @@ Cropping Structures .. _crop-scale: -.. figure:: crop.* - :alt: crop.pdf / crop.svg +.. kernel-figure:: crop.svg + :alt: crop.svg :align: center Image Cropping, Insertion and Scaling diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst index baf5f2483927..f761d3a93783 100644 --- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst @@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does .. _vbi-hsync: -.. figure:: vbi_hsync.* - :alt: vbi_hsync.pdf / vbi_hsync.svg +.. kernel-figure:: vbi_hsync.svg + :alt: vbi_hsync.svg :align: center **Figure 4.1. Line synchronization** @@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does .. _vbi-525: -.. figure:: vbi_525.* - :alt: vbi_525.pdf / vbi_525.svg +.. kernel-figure:: vbi_525.svg + :alt: vbi_525.svg :align: center **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)** @@ -240,8 +240,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does .. _vbi-625: -.. figure:: vbi_625.* - :alt: vbi_625.pdf / vbi_625.svg +.. kernel-figure:: vbi_625.svg + :alt: vbi_625.svg :align: center **Figure 4.3. ITU-R 625 line numbering** diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst index cd2870180208..0a54e4d95013 100644 --- a/Documentation/media/uapi/v4l/dev-subdev.rst +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -99,8 +99,8 @@ the video sensor and the host image processing hardware. .. _pipeline-scaling: -.. figure:: pipeline.* - :alt: pipeline.pdf / pipeline.svg +.. kernel-figure:: pipeline.dot + :alt: pipeline.dot :align: center Image Format Negotiation on Pipelines @@ -404,8 +404,8 @@ selection will refer to the sink pad format dimensions instead. .. _subdev-image-processing-crop: -.. figure:: subdev-image-processing-crop.* - :alt: subdev-image-processing-crop.pdf / subdev-image-processing-crop.svg +.. kernel-figure:: subdev-image-processing-crop.svg + :alt: subdev-image-processing-crop.svg :align: center **Figure 4.5. Image processing in subdevs: simple crop example** @@ -421,8 +421,8 @@ pad. .. _subdev-image-processing-scaling-multi-source: -.. figure:: subdev-image-processing-scaling-multi-source.* - :alt: subdev-image-processing-scaling-multi-source.pdf / subdev-image-processing-scaling-multi-source.svg +.. kernel-figure:: subdev-image-processing-scaling-multi-source.svg + :alt: subdev-image-processing-scaling-multi-source.svg :align: center **Figure 4.6. Image processing in subdevs: scaling with multiple sources** @@ -437,8 +437,8 @@ an area at location specified by the source crop rectangle from it. .. _subdev-image-processing-full: -.. figure:: subdev-image-processing-full.* - :alt: subdev-image-processing-full.pdf / subdev-image-processing-full.svg +.. kernel-figure:: subdev-image-processing-full.svg + :alt: subdev-image-processing-full.svg :align: center **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources** diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index e05fb1041363..7a1a0ac8e37a 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -141,8 +141,8 @@ enum v4l2_field Field Order, Top Field First Transmitted ======================================== -.. figure:: fieldseq_tb.* - :alt: fieldseq_tb.pdf / fieldseq_tb.svg +.. kernel-figure:: fieldseq_tb.svg + :alt: fieldseq_tb.svg :align: center @@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted Field Order, Bottom Field First Transmitted =========================================== -.. figure:: fieldseq_bt.* - :alt: fieldseq_bt.pdf / fieldseq_bt.svg +.. kernel-figure:: fieldseq_bt.svg + :alt: fieldseq_bt.svg :align: center diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst index 32d0c8743460..a4d64edc6200 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst @@ -33,8 +33,8 @@ Layout of macroblocks in memory is presented in the following figure. .. _nv12mt: -.. figure:: nv12mt.* - :alt: nv12mt.pdf / nv12mt.svg +.. kernel-figure:: nv12mt.svg + :alt: nv12mt.svg :align: center V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout @@ -50,8 +50,8 @@ interleaved. Height of the buffer is aligned to 32. .. _nv12mt_ex: -.. figure:: nv12mt_example.* - :alt: nv12mt_example.pdf / nv12mt_example.svg +.. kernel-figure:: nv12mt_example.svg + :alt: nv12mt_example.svg :align: center Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst index 21686f93c38f..04e9384e1be8 100644 --- a/Documentation/media/uapi/v4l/selection-api-003.rst +++ b/Documentation/media/uapi/v4l/selection-api-003.rst @@ -7,8 +7,8 @@ Selection targets .. _sel-targets-capture: -.. figure:: selection.* - :alt: selection.pdf / selection.svg +.. kernel-figure:: selection.svg + :alt: selection.svg :align: center Cropping and composing targets diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index d6152c907b8b..4fbf2e29e653 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -1514,8 +1514,8 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``. .. _bayer-patterns: -.. figure:: bayer.* - :alt: bayer.pdf / bayer.svg +.. figure:: bayer.svg + :alt: bayer.svg :align: center **Figure 4.8 Bayer Patterns**