lkml.org 
[lkml]   [2016]   [Nov]   [21]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[RFC PATCH] docs-rst: move the rules for svg and graphviz to Makefile.sphinx
    Date
    Not only media documents may have images. So, move the
    rules for building images from graphviz and from SVG to
    the Documentation makefile.

    With this change, if some Documentation subdir "foo"
    can now specify that he has SVG and/or DOT source images
    that are included inside the documentation.

    All it is needed is to create a Documentation/foo/Makefile with:

    DOTS += foo/bar.dot
    IMAGES += foo/foobar.svg

    and, at Makefile.sphinx, add a:

    include foo/Makefile

    The build system will generate the SVG image "bar.svg" from
    the graphviz "bar.dot" document for all documentation targets.

    If the documentation target is latexdocs or pdfdocs, it will
    also produce a "bar.pdf" image from "bar.svg", and a "foobar.pdf"
    from a SVG source image called "foobar.svg".

    Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
    ---

    NOTE:
    ====

    This is a RFC patch, based on this patch series:
    https://lkml.org/lkml/2016/11/20/89

    If you think it is worth, I'll write a documentation patch for the doc-guide/
    providing a complete guide about how to add an image at the Kernel's
    documentation.


    Documentation/Makefile.sphinx | 41 ++++++++++++++++-----
    Documentation/media/Makefile | 83 ++++++++++++++++---------------------------
    2 files changed, 63 insertions(+), 61 deletions(-)

    diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
    index 707c65337ebf..adc24ffa4c6a 100644
    --- a/Documentation/Makefile.sphinx
    +++ b/Documentation/Makefile.sphinx
    @@ -2,6 +2,8 @@
    # Makefile for Sphinx documentation
    #

    +include Documentation/media/Makefile
    +
    # You can set these variables from the command line.
    SPHINXBUILD = sphinx-build
    SPHINXOPTS =
    @@ -13,6 +15,29 @@ BUILDDIR = $(obj)/output
    PDFLATEX = xelatex
    LATEXOPTS = -interaction=batchmode

    +# Handle SVG and graphviz images
    +
    +DOTTGT := $(patsubst %.dot,%.svg,$(DOTS))
    +IMGDOT := $(patsubst %,$(srctree)/Documentation/%,$(DOTTGT))
    +
    +IMGTGT := $(patsubst %.svg,%.pdf,$(IMAGES))
    +IMGPDF := $(patsubst %,$(srctree)/Documentation/%,$(IMGTGT))
    +
    +cmd = $(echo-cmd) $(cmd_$(1))
    +
    +quiet_cmd_genpdf = GENPDF $2
    + cmd_genpdf = convert $2 $3
    +
    +quiet_cmd_gendot = DOT $2
    + cmd_gendot = dot -Tsvg $2 > $3
    +
    +%.pdf: %.svg
    + @$(call cmd,genpdf,$<,$@)
    +
    +%.svg: %.dot
    + @$(call cmd,gendot,$<,$@)
    +
    +
    # User-friendly check for sphinx-build
    HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi)

    @@ -54,7 +79,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 $2;\
    + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media mediaheaders;\
    BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
    $(SPHINXBUILD) \
    -b $2 \
    @@ -65,10 +90,10 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
    $(abspath $(srctree)/$(src)/$5) \
    $(abspath $(BUILDDIR)/$3/$4);

    -htmldocs:
    +htmldocs: $(IMGDOT)
    @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))

    -latexdocs:
    +latexdocs: $(IMGPDF)
    @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))

    ifeq ($(HAVE_PDFLATEX),0)
    @@ -79,15 +104,15 @@ pdfdocs:

    else # HAVE_PDFLATEX

    -pdfdocs: latexdocs
    +pdfdocs: latexdocs $(IMGPDF)
    $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex;)

    endif # HAVE_PDFLATEX

    -epubdocs:
    +epubdocs: $(IMGDOT)
    @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))

    -xmldocs:
    +xmldocs: $(IMGDOT)
    @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))

    # no-ops for the Sphinx toolchain
    @@ -97,8 +122,8 @@ mandocs:
    installmandocs:

    cleandocs:
    - $(Q)rm -rf $(BUILDDIR)
    - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
    + $(Q)rm -rf $(BUILDDIR) $(IMGDOT) $(IMGPDF)
    + $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media mediacleandocs

    endif # HAVE_SPHINX

    diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
    index 4d8e2ff378c4..b27c202beefb 100644
    --- a/Documentation/media/Makefile
    +++ b/Documentation/media/Makefile
    @@ -1,54 +1,35 @@
    # Rules to convert DOT and SVG to Sphinx images

    -SRC_DIR=$(srctree)/Documentation/media
    -
    -DOTS = \
    - uapi/v4l/pipeline.dot \
    -
    -IMAGES = \
    - typical_media_device.svg \
    - uapi/dvb/dvbstb.svg \
    - uapi/v4l/bayer.svg \
    - uapi/v4l/constraints.svg \
    - uapi/v4l/crop.svg \
    - uapi/v4l/fieldseq_bt.svg \
    - uapi/v4l/fieldseq_tb.svg \
    - uapi/v4l/nv12mt.svg \
    - uapi/v4l/nv12mt_example.svg \
    - uapi/v4l/pipeline.svg \
    - uapi/v4l/selection.svg \
    - uapi/v4l/subdev-image-processing-full.svg \
    - uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
    - uapi/v4l/subdev-image-processing-crop.svg \
    - uapi/v4l/vbi_525.svg \
    - uapi/v4l/vbi_625.svg \
    - uapi/v4l/vbi_hsync.svg \
    -
    -DOTTGT := $(patsubst %.dot,%.svg,$(DOTS))
    -IMGDOT := $(patsubst %,$(SRC_DIR)/%,$(DOTTGT))
    -
    -IMGTGT := $(patsubst %.svg,%.pdf,$(IMAGES))
    -IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT))
    -
    -cmd = $(echo-cmd) $(cmd_$(1))
    -
    -quiet_cmd_genpdf = GENPDF $2
    - cmd_genpdf = convert $2 $3
    -
    -quiet_cmd_gendot = DOT $2
    - cmd_gendot = dot -Tsvg $2 > $3
    -
    -%.pdf: %.svg
    - @$(call cmd,genpdf,$<,$@)
    -
    -%.svg: %.dot
    - @$(call cmd,gendot,$<,$@)
    +UAPI_V4L = media/uapi/v4l
    +
    +DOTS += \
    + $(UAPI_V4L)/pipeline.dot \
    +
    +IMAGES += \
    + media/typical_media_device.svg \
    + media/uapi/dvb/dvbstb.svg \
    + $(UAPI_V4L)/bayer.svg \
    + $(UAPI_V4L)/constraints.svg \
    + $(UAPI_V4L)/crop.svg \
    + $(UAPI_V4L)/fieldseq_bt.svg \
    + $(UAPI_V4L)/fieldseq_tb.svg \
    + $(UAPI_V4L)/nv12mt.svg \
    + $(UAPI_V4L)/nv12mt_example.svg \
    + $(UAPI_V4L)/pipeline.svg \
    + $(UAPI_V4L)/selection.svg \
    + $(UAPI_V4L)/subdev-image-processing-full.svg \
    + $(UAPI_V4L)/subdev-image-processing-scaling-multi-source.svg \
    + $(UAPI_V4L)/subdev-image-processing-crop.svg \
    + $(UAPI_V4L)/vbi_525.svg \
    + $(UAPI_V4L)/vbi_625.svg \
    + $(UAPI_V4L)/vbi_hsync.svg \

    # Rules to convert a .h file to inline RST documentation

    PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
    -UAPI = $(srctree)/include/uapi/linux
    -KAPI = $(srctree)/include/linux
    +SRC_DIR= $(srctree)/Documentation/media
    +UAPI = $(srctree)/include/uapi/linux
    +KAPI = $(srctree)/include/linux

    FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
    videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst
    @@ -96,16 +77,12 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception

    # Media build rules

    -.PHONY: all html epub xml latex
    +.PHONY: mediaheaders

    -all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
    -html: all
    -epub: all
    -xml: all
    -latex: $(IMGPDF) all
    +mediaheaders: $(IMGDOT) $(BUILDDIR) ${TARGETS}

    -clean:
    - -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
    +mediacleandocs:
    + $(Q)rm -f ${TARGETS} 2>/dev/null

    $(BUILDDIR):
    $(Q)mkdir -p $@
    --
    2.9.3

    \
     
     \ /
      Last update: 2016-11-21 10:49    [W:4.900 / U:0.004 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site