Re: [RFC PATCH 2/3] Documentation: switch to pdflatex for pdf generation

[Markus Heiser]

Am 10.08.2016 um 17:54 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:

> Looks like rst2pdf is not robust enough, especially for large documents.
> 
> Use recursive make on the Sphinx generated makefile to convert latex to
> pdf. The ugly detail is that pdf is generated into
> Documentation/output/latex.
> 
> Unfortunately, the pdflatex build generates huge amounts of build log
> noise, and also fails in the end. We'll fix that next.

A good starting point might be to ship our own tex-Makefile:

create a folder e.g. Documentation/sphinx-tex place your
Makefile (a copy of Sphinx's Makefile) in. In conf.py set
the 

  latex_additional_files = [
      "sphinx-text/Makefile"
  ]

In the sphinx-tex/Makefile set e.g.

  # Additional LaTeX options
  LATEXOPTS = -interaction=batchmode
  LATEX_ENV = max_print_line=120

  LATEX = $(LATEX_ENV) latex
  PDFLATEX = $(LATEX_ENV) pdflatex
  MAKEINDEX = $(LATEX_ENV) makeindex

this is what I do in my projects to separate my tex-Makefile settings
from the main sphinx-Makefile.

-- Markus --


> 
> Signed-off-by: Jani Nikula <jani.nikula@xxxxxxxxx>
> ---
> Documentation/Makefile.sphinx | 15 ++++++++-------
> 1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
> index d24a9f12a280..fc29e08085aa 100644
> --- a/Documentation/Makefile.sphinx
> +++ b/Documentation/Makefile.sphinx
> @@ -25,8 +25,8 @@ else ifneq ($(DOCBOOKS),)
> 
> else # HAVE_SPHINX
> 
> -# User-friendly check for rst2pdf
> -HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)
> +# User-friendly check for pdflatex
> +HAVE_PDFLATEX := $(shell if which pdflatex >/dev/null 2>&1; then echo 1; else echo 0; fi)
> 
> # Internal variables.
> PAPEROPT_a4     = -D latex_paper_size=a4
> @@ -44,12 +44,13 @@ htmldocs:
> 	$(call cmd,sphinx,html)
> 
> pdfdocs:
> -ifeq ($(HAVE_RST2PDF),0)
> -	$(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.)
> +ifeq ($(HAVE_PDFLATEX),0)
> +	$(warning The 'pdflatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
> 	@echo "  SKIP    Sphinx $@ target."
> -else # HAVE_RST2PDF
> -	$(call cmd,sphinx,pdf)
> -endif # HAVE_RST2PDF
> +else # HAVE_PDFLATEX
> +	$(call cmd,sphinx,latex)
> +	$(Q)$(MAKE) -C $(BUILDDIR)/latex
> +endif # HAVE_PDFLATEX
> 
> epubdocs:
> 	$(call cmd,sphinx,epub)
> -- 
> 2.1.4
>