linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>,
	"Jonathan Corbet" <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
	Mauro Carvalho Chehab <mchehab@infradead.org>,
	Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
	ksummit-discuss@lists.linuxfoundation.org,
	Mauro Carvalho Chehab <mchehab@kernel.org>
Subject: [RFC PATCH] docs-rst: move the rules for svg and graphviz to Makefile.sphinx
Date: Mon, 21 Nov 2016 07:48:50 -0200	[thread overview]
Message-ID: <4d2770fcc7a65dd1ad05387317bc1fb5c4b879be.1479721511.git.mchehab@s-opensource.com> (raw)

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

             reply	other threads:[~2016-11-21  9:48 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-11-21  9:48 Mauro Carvalho Chehab [this message]
2016-11-21 10:21 ` [RFC PATCH] docs-rst: move the rules for svg and graphviz to Makefile.sphinx Daniel Vetter
2016-11-21 10:51   ` Mauro Carvalho Chehab
2016-11-21 15:55     ` Daniel Vetter

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=4d2770fcc7a65dd1ad05387317bc1fb5c4b879be.1479721511.git.mchehab@s-opensource.com \
    --to=mchehab@s-opensource.com \
    --cc=corbet@lwn.net \
    --cc=ksummit-discuss@lists.linuxfoundation.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mchehab@infradead.org \
    --cc=mchehab@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).