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>
This commit is contained in:
Mauro Carvalho Chehab 2016-11-14 14:32:32 -02:00 committed by Jonathan Corbet
parent f390293479
commit 15a04d4e76
42 changed files with 60 additions and 33 deletions

View File

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

1
Documentation/media/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
*.pdf

View File

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

View File

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

View File

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 35 KiB

View File

Before

Width:  |  Height:  |  Size: 21 KiB

After

Width:  |  Height:  |  Size: 21 KiB

View File

@ -55,7 +55,7 @@ Overview
.. _stb_components:
.. figure:: intro_files/dvbstb.*
.. figure:: dvbstb.*
:alt: dvbstb.pdf / dvbstb.svg
:align: center

View File

Before

Width:  |  Height:  |  Size: 9.5 KiB

After

Width:  |  Height:  |  Size: 9.5 KiB

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 3.3 KiB

View File

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

View File

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

View File

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

View File

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

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

Before

Width:  |  Height:  |  Size: 1.9 KiB

After

Width:  |  Height:  |  Size: 1.9 KiB

View File

Before

Width:  |  Height:  |  Size: 5.1 KiB

After

Width:  |  Height:  |  Size: 5.1 KiB

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

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

View File

@ -7,7 +7,7 @@ Selection targets
.. _sel-targets-capture:
.. figure:: selection-api-003_files/selection.*
.. figure:: selection.png
:alt: selection.png
:align: center

View File

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

View File

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

View File

Before

Width:  |  Height:  |  Size: 4.5 KiB

After

Width:  |  Height:  |  Size: 4.5 KiB

View File

Before

Width:  |  Height:  |  Size: 2.0 KiB

After

Width:  |  Height:  |  Size: 2.0 KiB

View File

Before

Width:  |  Height:  |  Size: 2.3 KiB

After

Width:  |  Height:  |  Size: 2.3 KiB

View File

Before

Width:  |  Height:  |  Size: 906 B

After

Width:  |  Height:  |  Size: 906 B

View File

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