Re: [RFC PATCH] docs-rst: move the rules for svg and graphviz to Makefile.sphinx

From: Daniel Vetter
Date: Mon Nov 21 2016 - 10:55:59 EST

Next message: Dmitry Vyukov: "Re: [RFC 2/3] abi_spec: hooks into syscall to allow pre and post checking"
Previous message: Mel Gorman: "[RFC PATCH] mm: page_alloc: High-order per-cpu page allocator"
In reply to: Mauro Carvalho Chehab: "Re: [RFC PATCH] docs-rst: move the rules for svg and graphviz to Makefile.sphinx"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

On Mon, Nov 21, 2016 at 08:51:55AM -0200, Mauro Carvalho Chehab wrote:
> Em Mon, 21 Nov 2016 11:21:27 +0100
> Daniel Vetter <daniel@xxxxxxxx> escreveu:
>
> > 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 ...
>
> Sure. Just pushed it to:
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=svg-images
>
> You can pull it from:
> git://linuxtv.org/mchehab/experimental.git svg-images
>
> I also just added a patch documenting it:
> https://git.linuxtv.org/mchehab/experimental.git/commit/?h=svg-images&id=ca3b1faaae9dcfcbf0f4a119bf5eb3df0cb6c001

Ok, thanks a lot. No promises since I'm drowning in stuff, but I'll try to
play around with this in drm a bit. Might still be good to make it all
land in 4.10 meanwhile, if it looks ok (which is probably not something my
opinion should matter on).
-Daniel

>
> Regards,
> Mauro
>
> > -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
> >
>
>
>
> Thanks,
> Mauro

--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Next message: Dmitry Vyukov: "Re: [RFC 2/3] abi_spec: hooks into syscall to allow pre and post checking"
Previous message: Mel Gorman: "[RFC PATCH] mm: page_alloc: High-order per-cpu page allocator"
In reply to: Mauro Carvalho Chehab: "Re: [RFC PATCH] docs-rst: move the rules for svg and graphviz to Makefile.sphinx"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]