| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20161121102127.gxy3p26ydfts6b7o@phenom.ffwll.local>
Date: Mon, 21 Nov 2016 11:21:27 +0100
From: Daniel Vetter <daniel@...ll.ch>
To: Mauro Carvalho Chehab <mchehab@...pensource.com>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
Jonathan Corbet <corbet@....net>,
Mauro Carvalho Chehab <mchehab@...radead.org>,
Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
ksummit-discuss@...ts.linuxfoundation.org,
Mauro Carvalho Chehab <mchehab@...nel.org>
Subject: Re: [RFC PATCH] docs-rst: move the rules for svg and graphviz to
Makefile.sphinx
On Mon, Nov 21, 2016 at 07:48:50AM -0200, Mauro Carvalho Chehab wrote:
> 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@...pensource.com>
Is there a branch somewhere with all this? I'd like to play around with
pulling graphs into the gpu docs ...
-Daniel
> ---
>
> 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
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@...r.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
Powered by blists - more mailing lists