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.10-rc1~170^2~39^2~1
X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=commitdiff_plain;h=15a04d4e76bd7ba755591f2369c574d8a0a7dc5d;p=linux.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 ec0c77d028db..a23d3c8b4848 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 000000000000..a1363379944a
--- /dev/null
+++ b/Documentation/media/.gitignore
@@ -0,0 +1 @@
+*.pdf
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index a7fb35291f6c..297b85c37ab9 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 f6086c159772..8f7490c9a8ef 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 d000d802b20f..000000000000
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 11b96a19a9ab..2ed5c23102b4 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 0fa75d90c3eb..000000000000
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 3ea733a8eef8..578c6f3d20f3 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 c9fb81cd32f3..000000000000
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 b82d837e4ff1..f81d906137ee 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 0bae28385dfa..000000000000
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 bf29b95dcd08..000000000000
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 200b668189bf..000000000000
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 fb4d0d45b216..c18e9c5427ee 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 ee3e37f04b6a..000000000000
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 29a806f839b4..000000000000
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 b78a8e8f6b35..000000000000
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 8f7a95b6eb4d..000000000000
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 50779a67c3fd..a7e1b4dae343 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 26598b23f80d..000000000000
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 4965b22ddb3a..000000000000
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 9f250a1df2f6..c8a77bc79f2f 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 15cb3b79f12c..207349c17ead 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 65105609374b..2f9c135dfadd 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 6da359e50668..deb1f6fb473b 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.