From: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Date: Mon, 14 Nov 2016 16:32:32 +0000 (-0200)
Subject: docs-rst: auto-generate PDF image files
X-Git-Tag: v4.14-rc1~1033^2~172^2~1
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=15a04d4e76bd7ba755591f2369c574d8a0a7dc5d;p=platform%2Fkernel%2Flinux-rpi.git

docs-rst: auto-generate PDF image files

The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ec0c77d..a23d3c8 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -54,7 +54,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
 #    e.g. "media" for the linux-tv book-set at ./Documentation/media
 
 quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
-      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\
+      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2;\
 	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
 	$(SPHINXBUILD) \
 	-b $2 \
@@ -98,6 +98,7 @@ installmandocs:
 
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
+	$(Q)$(MAKE) -C Documentation/media clean
 
 endif # HAVE_SPHINX
 
diff --git a/Documentation/media/.gitignore b/Documentation/media/.gitignore
new file mode 100644
index 0000000..a136337
--- /dev/null
+++ b/Documentation/media/.gitignore
@@ -0,0 +1 @@
+*.pdf
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index a7fb352..297b85c 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -10,8 +10,35 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
 
 TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 
-.PHONY: all
+IMAGES = \
+	typical_media_device.svg \
+	uapi/dvb/dvbstb.svg \
+	uapi/v4l/constraints.svg \
+	uapi/v4l/subdev-image-processing-full.svg \
+	uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
+	uapi/v4l/subdev-image-processing-crop.svg \
+
+IMGTGT := $(patsubst %.png,%.pdf,$(patsubst %.svg,%.pdf,$(IMAGES)))
+IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT))
+
+cmd = $(echo-cmd) $(cmd_$(1))
+
+quiet_cmd_genpdf = GENPDF  $2
+      cmd_genpdf = convert $2 $3
+
+%.pdf: %.svg
+	@$(call cmd,genpdf,$<,$@)
+
+.PHONY: all html epub xml latex
+
 all: $(BUILDDIR) ${TARGETS}
+html: all
+epub: all
+xml: all
+latex: $(IMGPDF) all
+
+clean:
+	-rm $(IMGTGT) 2>/dev/null
 
 $(BUILDDIR):
 	$(Q)mkdir -p $@
diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst
index f6086c1..8f7490c 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::  media_api_files/typical_media_device.*
-    :alt:    typical_media_device.svg
+.. figure::  typical_media_device.*
+    :alt:    typical_media_device.pdf / typical_media_device.svg
     :align:  center
 
     Typical Media Device
diff --git a/Documentation/media/media_api_files/typical_media_device.pdf b/Documentation/media/media_api_files/typical_media_device.pdf
deleted file mode 100644
index d000d80..0000000
Binary files a/Documentation/media/media_api_files/typical_media_device.pdf and /dev/null differ
diff --git a/Documentation/media/media_api_files/typical_media_device.svg b/Documentation/media/typical_media_device.svg
similarity index 100%
rename from Documentation/media/media_api_files/typical_media_device.svg
rename to Documentation/media/typical_media_device.svg
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.svg b/Documentation/media/uapi/dvb/dvbstb.svg
similarity index 100%
rename from Documentation/media/uapi/dvb/intro_files/dvbstb.svg
rename to Documentation/media/uapi/dvb/dvbstb.svg
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 11b96a1..2ed5c23 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -55,7 +55,7 @@ Overview
 
 .. _stb_components:
 
-.. figure::  intro_files/dvbstb.*
+.. figure::  dvbstb.*
     :alt:    dvbstb.pdf / dvbstb.svg
     :align:  center
 
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf b/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf
deleted file mode 100644
index 0fa75d9..0000000
Binary files a/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png b/Documentation/media/uapi/v4l/bayer.png
similarity index 100%
rename from Documentation/media/uapi/v4l/subdev-formats_files/bayer.png
rename to Documentation/media/uapi/v4l/bayer.png
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg b/Documentation/media/uapi/v4l/constraints.svg
similarity index 100%
rename from Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg
rename to Documentation/media/uapi/v4l/constraints.svg
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.png b/Documentation/media/uapi/v4l/crop.png
similarity index 100%
rename from Documentation/media/uapi/v4l/crop_files/crop.png
rename to Documentation/media/uapi/v4l/crop.png
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index 3ea733a..578c6f3 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_files/crop.*
-    :alt:    crop.pdf / crop.gif
+.. figure::  crop.png
+    :alt:    crop.png
     :align:  center
 
     Image Cropping, Insertion and Scaling
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.pdf b/Documentation/media/uapi/v4l/crop_files/crop.pdf
deleted file mode 100644
index c9fb81c..0000000
Binary files a/Documentation/media/uapi/v4l/crop_files/crop.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
index b82d837..f81d906 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 <VIDIOC_G_FMT>` does
 
 .. _vbi-hsync:
 
-.. figure::  dev-raw-vbi_files/vbi_hsync.*
-    :alt:    vbi_hsync.pdf / vbi_hsync.gif
+.. figure::  vbi_hsync.png
+    :alt:    vbi_hsync.png
     :align:  center
 
     **Figure 4.1. Line synchronization**
@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
 
 .. _vbi-525:
 
-.. figure::  dev-raw-vbi_files/vbi_525.*
-    :alt:    vbi_525.pdf / vbi_525.gif
+.. figure::  vbi_525.png
+    :alt:    vbi_525.png
     :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 <VIDIOC_G_FMT>` does
 
 .. _vbi-625:
 
-.. figure::  dev-raw-vbi_files/vbi_625.*
-    :alt:    vbi_625.pdf / vbi_625.gif
+.. figure::  vbi_625.png
+    :alt:    vbi_625.png
     :align:  center
 
     **Figure 4.3. ITU-R 625 line numbering**
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf
deleted file mode 100644
index 0bae283..0000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf
deleted file mode 100644
index bf29b95..0000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf
deleted file mode 100644
index 200b668..0000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
index fb4d0d4..c18e9c5 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::  dev-subdev_files/pipeline.*
-    :alt:    pipeline.pdf / pipeline.png
+.. figure::  pipeline.png
+    :alt:    pipeline.png
     :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::  dev-subdev_files/subdev-image-processing-crop.*
-    :alt:    subdev-image-processing-crop.svg
+.. figure::  subdev-image-processing-crop.*
+    :alt:    subdev-image-processing-crop.pdf / 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::  dev-subdev_files/subdev-image-processing-scaling-multi-source.*
-    :alt:    subdev-image-processing-scaling-multi-source.svg
+.. figure::  subdev-image-processing-scaling-multi-source.*
+    :alt:    subdev-image-processing-scaling-multi-source.pdf / 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::  dev-subdev_files/subdev-image-processing-full.*
-    :alt:    subdev-image-processing-full.svg
+.. figure::  subdev-image-processing-full.*
+    :alt:    subdev-image-processing-full.pdf / 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/dev-subdev_files/pipeline.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf
deleted file mode 100644
index ee3e37f..0000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf
deleted file mode 100644
index 29a806f..0000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf
deleted file mode 100644
index b78a8e8..0000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf
deleted file mode 100644
index 8f7a95b..0000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst
index 50779a6..a7e1b4d 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::  field-order_files/fieldseq_tb.*
-    :alt:    fieldseq_tb.pdf / fieldseq_tb.gif
+.. figure::  fieldseq_tb.png
+    :alt:    fieldseq_tb.png
     :align:  center
 
 
@@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted
 Field Order, Bottom Field First Transmitted
 ===========================================
 
-.. figure::  field-order_files/fieldseq_bt.*
-    :alt:    fieldseq_bt.pdf / fieldseq_bt.gif
+.. figure::  fieldseq_bt.png
+    :alt:    fieldseq_bt.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf
deleted file mode 100644
index 26598b2..0000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf
deleted file mode 100644
index 4965b22..0000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png b/Documentation/media/uapi/v4l/fieldseq_bt.png
similarity index 100%
rename from Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png
rename to Documentation/media/uapi/v4l/fieldseq_bt.png
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png b/Documentation/media/uapi/v4l/fieldseq_tb.png
similarity index 100%
rename from Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png
rename to Documentation/media/uapi/v4l/fieldseq_tb.png
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png b/Documentation/media/uapi/v4l/nv12mt.png
similarity index 100%
rename from Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png
rename to Documentation/media/uapi/v4l/nv12mt.png
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png b/Documentation/media/uapi/v4l/nv12mt_example.png
similarity index 100%
rename from Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
rename to Documentation/media/uapi/v4l/nv12mt_example.png
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png b/Documentation/media/uapi/v4l/pipeline.png
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png
rename to Documentation/media/uapi/v4l/pipeline.png
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
index 9f250a1..c8a77bc 100644
--- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
@@ -33,7 +33,7 @@ Layout of macroblocks in memory is presented in the following figure.
 
 .. _nv12mt:
 
-.. figure::  pixfmt-nv12mt_files/nv12mt.*
+.. figure::  nv12mt.png
     :alt:    nv12mt.png
     :align:  center
 
@@ -50,7 +50,7 @@ interleaved. Height of the buffer is aligned to 32.
 
 .. _nv12mt_ex:
 
-.. figure::  pixfmt-nv12mt_files/nv12mt_example.*
+.. figure::  nv12mt_example.png
     :alt:    nv12mt_example.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst
index 15cb3b7..207349c 100644
--- a/Documentation/media/uapi/v4l/selection-api-003.rst
+++ b/Documentation/media/uapi/v4l/selection-api-003.rst
@@ -7,7 +7,7 @@ Selection targets
 
 .. _sel-targets-capture:
 
-.. figure::  selection-api-003_files/selection.*
+.. figure::  selection.png
     :alt:    selection.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/selection-api-003_files/selection.png b/Documentation/media/uapi/v4l/selection.png
similarity index 100%
rename from Documentation/media/uapi/v4l/selection-api-003_files/selection.png
rename to Documentation/media/uapi/v4l/selection.png
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index 6510560..2f9c135 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1514,14 +1514,12 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
 
 .. _bayer-patterns:
 
-.. figure::  subdev-formats_files/bayer.*
+.. figure::  bayer.png
     :alt:    bayer.png
     :align:  center
 
     **Figure 4.8 Bayer Patterns**
 
-
-
 The following table lists existing packed Bayer formats. The data
 organization is given as an example for the first pixel only.
 
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg
rename to Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg
rename to Documentation/media/uapi/v4l/subdev-image-processing-full.svg
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg
rename to Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png b/Documentation/media/uapi/v4l/vbi_525.png
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png
rename to Documentation/media/uapi/v4l/vbi_525.png
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png b/Documentation/media/uapi/v4l/vbi_625.png
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png
rename to Documentation/media/uapi/v4l/vbi_625.png
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png b/Documentation/media/uapi/v4l/vbi_hsync.png
similarity index 100%
rename from Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png
rename to Documentation/media/uapi/v4l/vbi_hsync.png
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
index 6da359e..deb1f6f 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
@@ -129,8 +129,8 @@ Selection targets and flags are documented in
 
 .. _sel-const-adjust:
 
-.. figure::  vidioc-g-selection_files/constraints.*
-    :alt:    constraints.svg
+.. figure::  constraints.*
+    :alt:    constraints.pdf / constraints.svg
     :align:  center
 
     Size adjustments with constraint flags.