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@xxxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
