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 коммит произвёл Jonathan Corbet
Родитель f390293479
Коммит 15a04d4e76
42 изменённых файлов: 60 добавлений и 33 удалений

Просмотреть файл

@ -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 поставляемый Normal file
Просмотреть файл

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

Двоичный файл не отображается.

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 35 KiB

После

Ширина:  |  Высота:  |  Размер: 35 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 21 KiB

После

Ширина:  |  Высота:  |  Размер: 21 KiB

Просмотреть файл

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

Двоичный файл не отображается.

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 9.5 KiB

После

Ширина:  |  Высота:  |  Размер: 9.5 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 12 KiB

После

Ширина:  |  Высота:  |  Размер: 12 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 3.3 KiB

После

Ширина:  |  Высота:  |  Размер: 3.3 KiB

Просмотреть файл

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

Двоичные данные
Documentation/media/uapi/v4l/crop_files/crop.pdf

Двоичный файл не отображается.

Просмотреть файл

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

Двоичный файл не отображается.

Двоичный файл не отображается.

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 12 KiB

После

Ширина:  |  Высота:  |  Размер: 12 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 12 KiB

После

Ширина:  |  Высота:  |  Размер: 12 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 1.9 KiB

После

Ширина:  |  Высота:  |  Размер: 1.9 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 5.1 KiB

После

Ширина:  |  Высота:  |  Размер: 5.1 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 12 KiB

После

Ширина:  |  Высота:  |  Размер: 12 KiB

Просмотреть файл

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

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 11 KiB

После

Ширина:  |  Высота:  |  Размер: 11 KiB

Просмотреть файл

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

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 4.5 KiB

После

Ширина:  |  Высота:  |  Размер: 4.5 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 12 KiB

После

Ширина:  |  Высота:  |  Размер: 12 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 8.8 KiB

После

Ширина:  |  Высота:  |  Размер: 8.8 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 2.0 KiB

После

Ширина:  |  Высота:  |  Размер: 2.0 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 2.3 KiB

После

Ширина:  |  Высота:  |  Размер: 2.3 KiB

Просмотреть файл

До

Ширина:  |  Высота:  |  Размер: 906 B

После

Ширина:  |  Высота:  |  Размер: 906 B

Просмотреть файл

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