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>
2016-11-14 14:32:32 -02:00
parent f390293479
commit 15a04d4e76
42 changed files with 60 additions and 33 deletions
@@ -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

@@ -0,0 +1 @@
+*.pdf
@@ -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 $@
@@ -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
@@ -55,7 +55,7 @@ Overview

 .. _stb_components:

-.. figure::  intro_files/dvbstb.*
+.. figure::  dvbstb.*
    :alt:    dvbstb.pdf / dvbstb.svg
    :align:  center

@@ -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
@@ -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**
@@ -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**
@@ -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

@@ -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

@@ -7,7 +7,7 @@ Selection targets

 .. _sel-targets-capture:

-.. figure::  selection-api-003_files/selection.*
+.. figure::  selection.png
    :alt:    selection.png
    :align:  center

@@ -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.

@@ -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.