[v4] docs: experimental: build PDF with rst2pdf
Commit Message
Add an experimental PDF builder using rst2pdf.
This extension is only enabled when "pdf" builder is selected.
So, it won't interfere with normal documentation builds. I opted
to not add a try..except block, as the message is already
good enough if one tries to do a "make rst2pdf" but the extension
is missed:
Extension error:
Could not import extension rst2pdf.pdfbuilder (exception: No module named 'rst2pdf')
This won't affect "make pdfdocs", as it uses the "latex" builder
instead.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
v4:
- only enable the rst2pdf extension when required, e. g. when
$ make rst2pdf
is used.
Documentation/Makefile | 5 +++++
Documentation/conf.py | 20 ++++++++++++++------
Documentation/sphinx/load_config.py | 12 ++++++++++++
Documentation/userspace-api/media/Makefile | 1 +
Makefile | 4 ++--
5 files changed, 34 insertions(+), 8 deletions(-)
@@ -115,6 +115,10 @@ pdfdocs: latexdocs
endif # HAVE_PDFLATEX
+rst2pdf:
+ @$(srctree)/scripts/sphinx-pre-install --version-check
+ @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,pdf,$(var),pdf,$(var)))
+
epubdocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
@@ -140,6 +144,7 @@ dochelp:
@echo ' htmldocs - HTML'
@echo ' latexdocs - LaTeX'
@echo ' pdfdocs - PDF'
+ @echo ' rst2pdf - PDF, using experimental rst2pdf support'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' linkcheckdocs - check for broken external links'
@@ -118,6 +118,11 @@ autosectionlabel_maxdepth = 2
extensions.append("sphinx.ext.imgmath")
+# Enable experimental rst2pdf, if available and selected by the user
+for i in range(1, len(sys.argv)):
+ if sys.argv[i] == "pdf":
+ extensions.append('rst2pdf.pdfbuilder')
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -553,12 +558,15 @@ epub_exclude_files = ['search.html']
#
# See the Sphinx chapter of https://ralsina.me/static/manual.pdf
#
-# FIXME: Do not add the index file here; the result will be too big. Adding
-# multiple PDF files here actually tries to get the cross-referencing right
-# *between* PDF files.
-pdf_documents = [
- ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
-]
+
+# Add all LaTeX files to PDF documents as well
+pdf_documents = []
+for l in latex_documents:
+ doc = l[0]
+ fn = l[1].replace(".tex", "")
+ name = l[2]
+ authors = l[3]
+ pdf_documents.append((doc, fn, name, authors))
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
# the Docs). In a normal build, these are supplied from the Makefile via command
@@ -43,6 +43,18 @@ def loadConfig(namespace):
namespace['latex_documents'] = new_latex_docs
+ new_pdf_docs = []
+ pdf_documents = namespace['pdf_documents']
+
+ for l in pdf_documents:
+ if l[0].find(dir + '/') == 0:
+ has = True
+ fn = l[0][len(dir) + 1:]
+ new_pdf_docs.append((fn, l[1], l[2], l[3]))
+ break
+
+ namespace['pdf_documents'] = new_pdf_docs
+
# If there is an extra conf.py file, load it
if os.path.isfile(config_file):
sys.stdout.write("load additional sphinx-config: %s\n" % config_file)
@@ -59,6 +59,7 @@ all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
html: all
epub: all
xml: all
+pdf: all
latex: $(IMGPDF) all
linkcheck:
@@ -270,7 +270,7 @@ no-dot-config-targets := $(clean-targets) \
cscope gtags TAGS tags help% %docs check% coccicheck \
$(version_h) headers headers_% archheaders archscripts \
%asm-generic kernelversion %src-pkg dt_binding_check \
- outputmakefile rustfmt rustfmtcheck
+ outputmakefile rustfmt rustfmtcheck rst2pdf
# Installation targets should not require compiler. Unfortunately, vdso_install
# is an exception where build artifacts may be updated. This must be fixed.
no-compiler-targets := $(no-dot-config-targets) install dtbs_install \
@@ -1816,7 +1816,7 @@ $(help-board-dirs): help-%:
# Documentation targets
# ---------------------------------------------------------------------------
-DOC_TARGETS := xmldocs latexdocs pdfdocs htmldocs epubdocs cleandocs \
+DOC_TARGETS := xmldocs latexdocs pdfdocs rst2pdf htmldocs epubdocs cleandocs \
linkcheckdocs dochelp refcheckdocs
PHONY += $(DOC_TARGETS)
$(DOC_TARGETS):