lkml.org 
[lkml]   [2020]   [Dec]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH RFC v2] docs: experimental: build PDF with rst2pdf
On Fri, Dec 11, 2020 at 05:03:50PM -0700, Jonathan Corbet wrote:
> The right solution is probably something like this:
>
> try:
> import rst2pdf
> extensions.append('rst2pdf.pdfbuilder')
> except ModuleNotFoundError:
> pass # no rst2pdf for you

I tested it, but it still fails, and the error message is even more cryptic:

Sphinx error:
Builder name pdf not registered or available through entry point
make[1]: *** [Documentation/Makefile:120: rst2pdf] Error 2
make: *** [Makefile:1663: rst2pdf] Error 2

It seems to me that the missing dependency should be treated in the Makefile
target rather than in Sphinx. Looking through the Makefile, I took inspiration
from the latex version and did the following:

HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi)


ifeq ($(HAVE_RST2PDF),0)

rst2pdf:
$(warning The 'rst2pdf' python module was not found. Make sure you have it installed to produce PDF output.)
@echo " SKIP Sphinx $@ target."

else # HAVE_RST2PDF

rst2pdf:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var)))

endif # HAVE_RST2PDF

With this, the following message is shown in case it isn't installed:

Documentation/Makefile:122: The 'rst2pdf' python module was not found. Make sure you have it installed to produce PDF output.
SKIP Sphinx rst2pdf target.

But with that check on the Makefile in place, on the Sphinx side, we can indeed
just do Jon's snippet to only add the extension if it is installed. Another
option would be to split the 'try' into 'try' and 'else', where the 'else' only
executes if the 'try' is succesful. The benefit is that this makes it clearer
that only the import is being "tried":

# Enable experimental rst2pdf, if available
try:
import rst2pdf
except ModuleNotFoundError:
pass
else:
extensions.append("rst2pdf.pdfbuilder")

Something interesting I noticed is that when building with Sphinx 3, and if
rst2pdf is installed, even when building other targets, like htmldocs, (since
the rst2pdf extension is added based on rst2pdf being installed and not if it is
being used) the following is printed:

WARNING: the rst2pdf.pdfbuilder extension is not safe for parallel writing
WARNING: doing serial write

Looking into rst2pdf's pdfbuilder.py, indeed 'parallel_write_safe' is False, so
we should probably make sure rst2pdf isn't negatively impacting build time for
other formats before merging this patch.

Thanks,
Nícolas

\
 
 \ /
  Last update: 2020-12-28 18:23    [W:0.029 / U:0.588 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site