[dpdk-dev,v2,1/4] 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  |   33 ++++++++++++++++++++++++++++++++-
 mk/rte.sdkroot.mk |    3 ++-
 2 files changed, 34 insertions(+), 2 deletions(-)
  

2015-01-30 18:13, John McNamara:
> 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>

>  ifndef V
>  RTE_SPHINX_VERBOSE := -q
> +RTE_PDFLATEX_VERBOSE := > /dev/null 2>&1

By redirecting everything in /dev/null, you won't see any error.
But pdflatex is an horrible software.
If I remember well, it's very difficult to filter only errors.
You could try "-interaction batchmode" for quiet mode and
"-interaction nonstopmode" for verbose mode.

> +DEFAULT_DPI ?= 300

It's better to prefix this global variable with RTE_ or DPDK_

> -clean: api-html-clean guides-html-clean
> +clean: api-html-clean guides-html-clean guides-latex-clean

Why not guides-pdf-clean?

> +pdf: pdf-rel_notes pdf-linux_gsg pdf-freebsd_gsg pdf-prog_guide \
> +	pdf-sample_app_ug pdf-testpmd_app_ug

In general, it's a bad idea to create virtual targets where it could
be a file. Example: the real file $(RTE_OUTPUT)/doc/.../rel_notes.pdf
would be a better target than pdf-rel_notes.
But maybe it's too difficult to have the full dependency chain to make
it able of recompiling only needed parts when needed.

> +pdf-%:
> +	@echo 'creating' $* 'pdf ...'
> +        # 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/$*
> +
> +        # Convert the svg files to png.
> +	$(eval svg_files=$(notdir $(wildcard $(RTE_SDK)/doc/guides/$*/img/*.svg)))
> +	$(eval svg_files=$(patsubst %.svg, %, $(svg_files)))
> +	@for svg in $(svg_files); do \

You could use $(svg_files:.svg=) instead of doing a patsubst above.

> +		inkscape -d $(DEFAULT_DPI) -D -b ffffff  \
> +			-f $(RTE_SDK)/doc/guides/$*/img/$$svg.svg \
> +			-e $(RTE_OUTPUT)/doc/latex/guides/$*/$$svg.png \
> +				$(RTE_PDFLATEX_VERBOSE); \
> +	done
> +
> +        # Change the svg image includes to png in the latex docs.
> +	$(Q)sed -i 's/\.svg/.png/g' $(RTE_OUTPUT)/doc/latex/guides/$*/*.tex

No, you could avoid that if every image references where x.* instead of x.svg or x.png.
The image extension should always be .* in rst to be format agnostic.
Then there is a (configurable) rule to choose the best format.

> +
> +        # Convert the latex to pdf.
> +	$(Q)$(MAKE) -C $(RTE_OUTPUT)/doc/latex/guides/$* \
> +		all-pdf $(RTE_PDFLATEX_VERBOSE)

Indentation is broken in this whole rule.

> --- a/mk/rte.sdkroot.mk
> +++ b/mk/rte.sdkroot.mk
> @@ -101,9 +101,10 @@ testall:
>  install uninstall:
>  	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
>  
> -.PHONY: doc help
> +.PHONY: doc help pdf
>  doc: doc-all
>  help: doc-help
> +pdf: doc-pdf
>  doc-%:
>  	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*

Why having a pdf rule? It seems not consistent. doc-pdf is enough.

Thanks
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Friday, January 30, 2015 8:52 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v2 1/4] mk: Add 'make doc-pdf' target to
> convert guide docs to pdf

Hi Thomas,

Thanks for the feedback.


> 2015-01-30 18:13, John McNamara:
> >  ifndef V
> >  RTE_SPHINX_VERBOSE := -q
> > +RTE_PDFLATEX_VERBOSE := > /dev/null 2>&1
> 
> By redirecting everything in /dev/null, you won't see any error.
> But pdflatex is an horrible software.
> If I remember well, it's very difficult to filter only errors.
> You could try "-interaction batchmode" for quiet mode and "-interaction
> nonstopmode" for verbose mode.


Yes. This is a bit of a blunt instrument. Sphinx generates an intermediate Makefile to build PDFs and I didn't have much control over that. I've changed the rule to call pdflatex directly in order to pass the "--interaction" switch.

I wasn't able to find a clean solution to keep inkscape quiet on the commandline, so that still pipes to /dev/null in non-verbose mode. Perhaps you will have a better idea on that.


> > -clean: api-html-clean guides-html-clean
> > +clean: api-html-clean guides-html-clean guides-latex-clean
> 
> Why not guides-pdf-clean?

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


> > +pdf: pdf-rel_notes pdf-linux_gsg pdf-freebsd_gsg pdf-prog_guide \
> > +	pdf-sample_app_ug pdf-testpmd_app_ug
> 
> In general, it's a bad idea to create virtual targets where it could be a
> file. Example: the real file $(RTE_OUTPUT)/doc/.../rel_notes.pdf
> would be a better target than pdf-rel_notes.
> But maybe it's too difficult to have the full dependency chain to make it
> able of recompiling only needed parts when needed.

Okay. I've refactored this to add *.pdf targets. As a side-effect it removes all of the conf.py files in the guides directories and makes the pdf build more generic.



> > +        # Change the svg image includes to png in the latex docs.
> > +	$(Q)sed -i 's/\.svg/.png/g' $(RTE_OUTPUT)/doc/latex/guides/$*/*.tex
> 
> No, you could avoid that if every image references where x.* instead of
> x.svg or x.png.
> The image extension should always be .* in rst to be format agnostic.
> Then there is a (configurable) rule to choose the best format.

This works for the html output but Sphinx throws a warning for the latex output since Sphinx doesn't support svg for that target. As a result the relative image include in the Latex file is incorrect and fails. So the sed conversion is a workaround.


> > -.PHONY: doc help
> > +.PHONY: doc help pdf
> >  doc: doc-all
> >  help: doc-help
> > +pdf: doc-pdf
> >  doc-%:
> >  	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*
> 
> Why having a pdf rule? It seems not consistent. doc-pdf is enough.

Yes. Agreed. I've removed the high level pdf rule. The patch no longer touches rte.sdkroot.mk.

V3 patch to follow.

John.
--
  

2015-02-02 13:10, Mcnamara, John:
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > > +        # Change the svg image includes to png in the latex docs.
> > > +	$(Q)sed -i 's/\.svg/.png/g' $(RTE_OUTPUT)/doc/latex/guides/$*/*.tex
> > 
> > No, you could avoid that if every image references where x.* instead of
> > x.svg or x.png.
> > The image extension should always be .* in rst to be format agnostic.
> > Then there is a (configurable) rule to choose the best format.
> 
> This works for the html output but Sphinx throws a warning for the
> latex output since Sphinx doesn't support svg for that target. As a
> result the relative image include in the Latex file is incorrect and
> fails. So the sed conversion is a workaround.

I think it's possible. Look at this link:
http://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-specify-png-image-formats-for-html-builds-and-pdf-im
In this example, SVG files are converted into PDF files, not PNG.
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Monday, February 2, 2015 1:35 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v2 1/4] mk: Add 'make doc-pdf' target to
> convert guide docs to pdf
> 
> I think it's possible. Look at this link:
> http://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-
> specify-png-image-formats-for-html-builds-and-pdf-im
> In this example, SVG files are converted into PDF files, not PNG.

Hi Thomas,

Using image.* will work for latex/pdf but only if the pngs are converted in the source directory (as opposed to the build directory) since Sphinx requires them to be available at the latex compile time.

I'll modify the patch to work that way.

Regards,

John
--