diff mbox

[dpdk-dev,v4,1/5] mk: Add 'make doc-pdf' target to convert guide docs to pdf

Message ID 1422972678-7982-2-git-send-email-john.mcnamara@intel.com (mailing list archive)
State Superseded, archived
Headers

Commit Message

Mcnamara, John Feb. 3, 2015, 2:11 p.m. UTC 
Added make system support for building PDF versions of
the guides. Requires Python Sphinx and TexLive Full.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---
 mk/rte.sdkdoc.mk |   43 ++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 42 insertions(+), 1 deletions(-)

Comments

Iremonger, Bernard Feb. 16, 2015, 12:19 p.m. UTC | #1 
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of John McNamara
> Sent: Tuesday, February 3, 2015 2:11 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v4 1/5] mk: Add 'make doc-pdf' target to convert guide docs to pdf
> 
> Added make system support for building PDF versions of the guides. Requires Python Sphinx and
> TexLive Full.
> 
> Signed-off-by: John McNamara <john.mcnamara@intel.com>
> ---
>  mk/rte.sdkdoc.mk |   43 ++++++++++++++++++++++++++++++++++++++++++-
>  1 files changed, 42 insertions(+), 1 deletions(-)
> 
> diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk index dabc0d6..e09628f 100644
> --- a/mk/rte.sdkdoc.mk
> +++ b/mk/rte.sdkdoc.mk
> @@ -37,13 +37,24 @@ endif
>  endif
> 
>  RTE_SPHINX_BUILD = sphinx-build
> +RTE_PDFLATEX_VERBOSE := --interaction=nonstopmode
> +
>  ifndef V
>  RTE_SPHINX_VERBOSE := -q
> +RTE_PDFLATEX_VERBOSE := --interaction=batchmode RTE_INKSCAPE_VERBOSE :=
> +> /dev/null 2>&1
>  endif
>  ifeq '$V' '0'
>  RTE_SPHINX_VERBOSE := -q
> +RTE_PDFLATEX_VERBOSE := --interaction=batchmode RTE_INKSCAPE_VERBOSE :=
> +> /dev/null 2>&1
>  endif
> 
> +RTE_GUIDE_PDFS := $(filter %/, $(wildcard $(RTE_SDK)/doc/guides/*/))
> +RTE_GUIDE_PDFS :=
> +$(RTE_GUIDE_PDFS:$(RTE_SDK)/doc/guides%=$(RTE_OUTPUT)/doc/latex/guides%
> +) RTE_GUIDE_PDFS := $(RTE_GUIDE_PDFS:%/=%.pdf) RTE_DEFAULT_DPI ?= 300
> +
>  .PHONY: help
>  help:
>  	@cat $(RTE_SDK)/doc/build-sdk-quick.txt
> @@ -53,7 +64,7 @@ help:
>  all: api-html guides-html
> 
>  .PHONY: clean
> -clean: api-html-clean guides-html-clean
> +clean: api-html-clean guides-html-clean guides-latex-clean

Hi John,

Would it be clearer to have a  guides-pdf-clean target  instead of guides-latex-clean given that there is a doc-pdf target?

Regards,

Bernard.



> 
>  .PHONY: api-html
>  api-html: api-html-clean
> @@ -83,3 +94,33 @@ guides-%:
>  	@echo 'sphinx for guides...'
>  	$(Q)$(RTE_SPHINX_BUILD) -b $* $(RTE_SPHINX_VERBOSE) \
>  		-c $(RTE_SDK)/doc/guides $(RTE_SDK)/doc/guides $(RTE_OUTPUT)/doc/$*/guides
> +
> +
> +pdf: $(RTE_GUIDE_PDFS)
> +
> +.SECONDEXPANSION:
> +# Use wildcard expansion to avoid * expansion issue with make 3.82.
> +$(RTE_OUTPUT)/doc/latex/guides/%.pdf: $$(wildcard $(RTE_SDK)/doc/guides/%/*.rst)
> +	@echo 'creating' $* 'pdf ...'
> +
> +	@# Convert the svg files to png for pdflatex.
> +	$(eval tmp_images = $(wildcard $(RTE_SDK)/doc/guides/$*/img/*.svg))
> +	$(Q)for image in $(tmp_images:.svg=); do \
> +		inkscape -d $(RTE_DEFAULT_DPI) -D -b ffffff \
> +			-f $$image.svg -e $$image.png $(RTE_INKSCAPE_VERBOSE); \
> +	done
> +
> +	@# Generate the latex files.
> +	$(Q)$(RTE_SPHINX_BUILD) -b latex $(RTE_SPHINX_VERBOSE) \
> +		-c $(RTE_SDK)/doc/guides  $(RTE_SDK)/doc/guides/$* \
> +		$(RTE_OUTPUT)/doc/latex/guides/$*
> +
> +	@# Remove the generated png files.
> +	$(Q)rm -f $(tmp_images:.svg=.png)
> +
> +	@# Generate the pdf files.
> +	$(Q)sed -i 's/LATEXOPTS =/LATEXOPTS = $(RTE_PDFLATEX_VERBOSE)/' \
> +		$(RTE_OUTPUT)/doc/latex/guides/$*/Makefile
> +	$(Q)make all-pdf -s -C $(RTE_OUTPUT)/doc/latex/guides/$*
> +
> +	$(Q)mv $(RTE_OUTPUT)/doc/latex/guides/$*/dpdk_doc.pdf $@
> --
> 1.7.4.1
Mcnamara, John Feb. 16, 2015, 12:55 p.m. UTC | #2 
> -----Original Message-----
> From: Iremonger, Bernard
> Sent: Monday, February 16, 2015 12:20 PM
> To: Mcnamara, John; dev@dpdk.org
> Subject: RE: [dpdk-dev] [PATCH v4 1/5] mk: Add 'make doc-pdf' target to
> convert guide docs to pdf
> 
> >
> >  .PHONY: clean
> > -clean: api-html-clean guides-html-clean
> > +clean: api-html-clean guides-html-clean guides-latex-clean
> 
> Hi John,
> 
> Would it be clearer to have a  guides-pdf-clean target  instead of guides-
> latex-clean given that there is a doc-pdf target?

Hi Bernard,

Thomas made the same comment on an earlier patch so clearly it isn't obvious where the rule comes from:

    http://dpdk.org/ml/archives/dev/2015-January/012099.html

The eason is that it is re-using the existing clean rule. My reply is here:

    http://dpdk.org/ml/archives/dev/2015-February/012241.html

    > Sphinx creates build/doc/html and build/doc/latex directories (not /build/doc/pdf) so this just reuses the existing guides-%-clean rule.

John
Iremonger, Bernard Feb. 16, 2015, 2:16 p.m. UTC | #3 
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of John McNamara
> > Sent: Tuesday, February 3, 2015 2:11 PM
> > To: dev@dpdk.org
> > Subject: [dpdk-dev] [PATCH v4 1/5] mk: Add 'make doc-pdf' target to
> > convert guide docs to pdf
> >
> > Added make system support for building PDF versions of the guides.
> > Requires Python Sphinx and TexLive Full.
> >
> > Signed-off-by: John McNamara <john.mcnamara@intel.com>

Acked-by: Bernard Iremonger <bernard.iremonger@intel.com>
diff mbox

Patch

diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index dabc0d6..e09628f 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -37,13 +37,24 @@  endif
 endif
 
 RTE_SPHINX_BUILD = sphinx-build
+RTE_PDFLATEX_VERBOSE := --interaction=nonstopmode
+
 ifndef V
 RTE_SPHINX_VERBOSE := -q
+RTE_PDFLATEX_VERBOSE := --interaction=batchmode
+RTE_INKSCAPE_VERBOSE := > /dev/null 2>&1
 endif
 ifeq '$V' '0'
 RTE_SPHINX_VERBOSE := -q
+RTE_PDFLATEX_VERBOSE := --interaction=batchmode
+RTE_INKSCAPE_VERBOSE := > /dev/null 2>&1
 endif
 
+RTE_GUIDE_PDFS := $(filter %/, $(wildcard $(RTE_SDK)/doc/guides/*/))
+RTE_GUIDE_PDFS := $(RTE_GUIDE_PDFS:$(RTE_SDK)/doc/guides%=$(RTE_OUTPUT)/doc/latex/guides%)
+RTE_GUIDE_PDFS := $(RTE_GUIDE_PDFS:%/=%.pdf)
+RTE_DEFAULT_DPI ?= 300
+
 .PHONY: help
 help:
 	@cat $(RTE_SDK)/doc/build-sdk-quick.txt
@@ -53,7 +64,7 @@  help:
 all: api-html guides-html
 
 .PHONY: clean
-clean: api-html-clean guides-html-clean
+clean: api-html-clean guides-html-clean guides-latex-clean
 
 .PHONY: api-html
 api-html: api-html-clean
@@ -83,3 +94,33 @@  guides-%:
 	@echo 'sphinx for guides...'
 	$(Q)$(RTE_SPHINX_BUILD) -b $* $(RTE_SPHINX_VERBOSE) \
 		-c $(RTE_SDK)/doc/guides $(RTE_SDK)/doc/guides $(RTE_OUTPUT)/doc/$*/guides
+
+
+pdf: $(RTE_GUIDE_PDFS)
+
+.SECONDEXPANSION:
+# Use wildcard expansion to avoid * expansion issue with make 3.82.
+$(RTE_OUTPUT)/doc/latex/guides/%.pdf: $$(wildcard $(RTE_SDK)/doc/guides/%/*.rst)
+	@echo 'creating' $* 'pdf ...'
+
+	@# Convert the svg files to png for pdflatex.
+	$(eval tmp_images = $(wildcard $(RTE_SDK)/doc/guides/$*/img/*.svg))
+	$(Q)for image in $(tmp_images:.svg=); do \
+		inkscape -d $(RTE_DEFAULT_DPI) -D -b ffffff \
+			-f $$image.svg -e $$image.png $(RTE_INKSCAPE_VERBOSE); \
+	done
+
+	@# Generate the latex files.
+	$(Q)$(RTE_SPHINX_BUILD) -b latex $(RTE_SPHINX_VERBOSE) \
+		-c $(RTE_SDK)/doc/guides  $(RTE_SDK)/doc/guides/$* \
+		$(RTE_OUTPUT)/doc/latex/guides/$*
+
+	@# Remove the generated png files.
+	$(Q)rm -f $(tmp_images:.svg=.png)
+
+	@# Generate the pdf files.
+	$(Q)sed -i 's/LATEXOPTS =/LATEXOPTS = $(RTE_PDFLATEX_VERBOSE)/' \
+		$(RTE_OUTPUT)/doc/latex/guides/$*/Makefile
+	$(Q)make all-pdf -s -C $(RTE_OUTPUT)/doc/latex/guides/$*
+
+	$(Q)mv $(RTE_OUTPUT)/doc/latex/guides/$*/dpdk_doc.pdf $@