[PATCH v4] docs: experimental: build PDF with rst2pdf
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Date: 2021-03-25 12:38:47
Also in:
linux-kbuild, linux-media, lkml
Subsystem:
documentation, documentation scripts, kernel build + files below scripts/ (unless maintained elsewhere), media input infrastructure (v4l/dvb), the rest · Maintainers:
Jonathan Corbet, Mauro Carvalho Chehab, Nathan Chancellor, Nicolas Schier, Linus Torvalds
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(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9c42dde97671..42b76f25681f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile@@ -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'
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 879e86dbea66..217a9e682099 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py@@ -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
diff --git a/Documentation/sphinx/load_config.py b/Documentation/sphinx/load_config.py
index eeb394b39e2c..8266afd438aa 100644
--- a/Documentation/sphinx/load_config.py
+++ b/Documentation/sphinx/load_config.py@@ -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)
diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile
index 81a4a1a53bce..8c6b3ac4ecb0 100644
--- a/Documentation/userspace-api/media/Makefile
+++ b/Documentation/userspace-api/media/Makefile@@ -59,6 +59,7 @@ all: $(IMGDOT) $(BUILDDIR) ${TARGETS} html: all epub: all xml: all +pdf: all latex: $(IMGPDF) all linkcheck:
diff --git a/Makefile b/Makefile
index 193ebb83c34a..741c580b3626 100644
--- a/Makefile
+++ b/Makefile@@ -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):
--
2.30.2