[dpdk-dev] [PATCH v2 1/4] mk: Add 'make doc-pdf' target to convert guide docs to pdf

Mcnamara, John john.mcnamara at intel.com
Mon Feb 2 14:10:15 CET 2015


> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon at 6wind.com]
> Sent: Friday, January 30, 2015 8:52 PM
> To: Mcnamara, John
> Cc: dev at 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.
-- 




More information about the dev mailing list