Merge branch 'mauro-pdf' into docs-mw

Here it is the second version of the PDF series. I opted to split one of the patches in 3, to have a clearer changelog and description. Also, archlinux LXC image download started working again, so I added an extra patch addressing texlive packae dependencies. This series is taking me a way more time than antecipated. This series as 3 goals: 1. Fix a pre-Sphinx 1.7 PDF variable that got renamed, but our Makefile still uses the old one that is not supported since Sphinx 1.7; 2. Fix broken or incomplete texlive dependencies on several distros; 4. "modernize" conf.py to solve font conflicts related to UTF-8 and non-UTF fonts from [T1]{fontenc} LaTeX package. Using fontenc with xelatex is problematic, as documented at https://www.sphinx-doc.org/en/master/latex.html Please notice that: - It doesn't pretend to fix all PDF issues. It focus only at the above; - there are still distros where PDF builds fail either partially or as a hole. On my checks, those are due to problematic texlive packages shipped on such distros; - it doesn't touch/address/alter anyhing related to kfigure.py. as such, it doesn't touch/change/improve/drop anything with regards ImageMagick and/or Inkscape.
2026-05-14 02:59:19 -04:00 · 2025-08-21 14:09:21 -06:00
parent f51fe3b7e4 c6e2391285
commit ee9a669193
3 changed files with 101 additions and 55 deletions
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -60,8 +60,8 @@ ifeq ($(HAVE_LATEXMK),1)
 endif #HAVE_LATEXMK

 # Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
+PAPEROPT_a4     = -D latex_elements.papersize=a4paper
+PAPEROPT_letter = -D latex_elements.papersize=letterpaper
 ALLSPHINXOPTS   = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
 ALLSPHINXOPTS   += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
 ifneq ($(wildcard $(srctree)/.config),)
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -9,6 +9,8 @@ import os
 import shutil
 import sys

+from  textwrap import dedent
+
 import sphinx

 # If extensions (or modules to document with autodoc) are in another directory,
@@ -51,11 +53,13 @@ else:
    dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
    dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")

-# Properly handle include/exclude patterns
-# ----------------------------------------
+# Properly handle directory patterns and LaTeX docs
+# -------------------------------------------------

-def update_patterns(app, config):
+def config_init(app, config):
    """
+    Initialize path-dependent variabled
+
    On Sphinx, all directories are relative to what it is passed as
    SOURCEDIR parameter for sphinx-build. Due to that, all patterns
    that have directory names on it need to be dynamically set, after
@@ -86,6 +90,38 @@ def update_patterns(app, config):

        config.exclude_patterns.append(rel_path)

+    # LaTeX and PDF output require a list of documents with are dependent
+    # of the app.srcdir. Add them here
+
+    # When SPHINXDIRS is used, we just need to get index.rst, if it exists
+    if not os.path.samefile(doctree, app.srcdir):
+        doc = os.path.basename(app.srcdir)
+        fname = "index"
+        if os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
+            latex_documents.append((fname, doc + ".tex",
+                                    "Linux %s Documentation" % doc.capitalize(),
+                                    "The kernel development community",
+                                    "manual"))
+            return
+
+    # When building all docs, or when a main index.rst doesn't exist, seek
+    # for it on subdirectories
+    for doc in os.listdir(app.srcdir):
+        fname = os.path.join(doc, "index")
+        if not os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
+            continue
+
+        has = False
+        for l in latex_documents:
+            if l[0] == fname:
+                has = True
+                break
+
+        if not has:
+            latex_documents.append((fname, doc + ".tex",
+                                    "Linux %s Documentation" % doc.capitalize(),
+                                    "The kernel development community",
+                                    "manual"))

 # helper
 # ------
@@ -420,19 +456,27 @@ htmlhelp_basename = "TheLinuxKerneldoc"
 latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    "papersize": "a4paper",
+    "passoptionstopackages": dedent(r"""
+        \PassOptionsToPackage{svgnames}{xcolor}
+        % Avoid encoding troubles when creating indexes
+        \PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}
+    """),
    # The font size ('10pt', '11pt' or '12pt').
    "pointsize": "11pt",
+    # Needed to generate a .ind file
+    "printindex": r"\footnotesize\raggedright\printindex",
    # Latex figure (float) alignment
    # 'figure_align': 'htbp',
    # Don't mangle with UTF-8 chars
+    "fontenc": "",
    "inputenc": "",
    "utf8extra": "",
    # Set document margins
-    "sphinxsetup": """
+    "sphinxsetup": dedent(r"""
        hmargin=0.5in, vmargin=1in,
        parsedliteralwraps=true,
        verbatimhintsturnover=false,
-    """,
+    """),
    #
    # Some of our authors are fond of deep nesting; tell latex to
    # cope.
@@ -440,48 +484,22 @@ latex_elements = {
    "maxlistdepth": "10",
    # For CJK One-half spacing, need to be in front of hyperref
    "extrapackages": r"\usepackage{setspace}",
-    # Additional stuff for the LaTeX preamble.
-    "preamble": """
-        % Use some font with UTF-8 support with XeLaTeX
-        \\usepackage{fontspec}
-        \\setsansfont{DejaVu Sans}
-        \\setromanfont{DejaVu Serif}
-        \\setmonofont{DejaVu Sans Mono}
-    """,
+    "fontpkg": dedent(r"""
+        \usepackage{fontspec}
+        \setmainfont{DejaVu Serif}
+        \setsansfont{DejaVu Sans}
+        \setmonofont{DejaVu Sans Mono}
+        \newfontfamily\headingfont{DejaVu Serif}
+    """),
+    "preamble": dedent(r"""
+        % Load kerneldoc specific LaTeX settings
+        \input{kerneldoc-preamble.sty}
+    """)
 }

-# Load kerneldoc specific LaTeX settings
-latex_elements["preamble"] += """
-        % Load kerneldoc specific LaTeX settings
-        \\input{kerneldoc-preamble.sty}
-"""
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-# Sorted in alphabetical order
+# This will be filled up by config-inited event
 latex_documents = []

-# Add all other index files from Documentation/ subdirectories
-for fn in os.listdir("."):
-    doc = os.path.join(fn, "index")
-    if os.path.exists(doc + ".rst"):
-        has = False
-        for l in latex_documents:
-            if l[0] == doc:
-                has = True
-                break
-        if not has:
-            latex_documents.append(
-                (
-                    doc,
-                    fn + ".tex",
-                    "Linux %s Documentation" % fn.capitalize(),
-                    "The kernel development community",
-                    "manual",
-                )
-            )
-
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 # latex_logo = None
@@ -577,4 +595,4 @@ loadConfig(globals())
 def setup(app):
    """Patterns need to be updated at init time on older Sphinx versions"""

-    app.connect('config-inited', update_patterns)
+    app.connect('config-inited', config_init)
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -764,9 +764,6 @@ class SphinxDependencyChecker(MissingCheckers):

        if self.pdf:
            pdf_pkgs = {
-                "texlive-lang-chinese": [
-                    "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty",
-                ],
                "fonts-dejavu": [
                    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
                ],
@@ -775,6 +772,15 @@ class SphinxDependencyChecker(MissingCheckers):
                    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
                    "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc",
                ],
+                "tex-gyre": [
+                    "/usr/share/texmf/tex/latex/tex-gyre/tgtermes.sty"
+                ],
+                "texlive-fonts-recommended": [
+                    "/usr/share/texlive/texmf-dist/fonts/tfm/adobe/zapfding/pzdr.tfm",
+                ],
+                "texlive-lang-chinese": [
+                    "/usr/share/texlive/texmf-dist/tex/latex/ctex/ctexhook.sty",
+                ],
            }

            for package, files in pdf_pkgs.items():
@@ -895,7 +901,7 @@ class SphinxDependencyChecker(MissingCheckers):
            "dot":           "graphviz",
            "python-sphinx": "python3-sphinx",
            "virtualenv":    "python3-virtualenv",
-            "xelatex":       "texlive-xetex-bin",
+            "xelatex":       "texlive-xetex-bin texlive-dejavu",
            "yaml":          "python3-pyyaml",
        }

@@ -931,7 +937,7 @@ class SphinxDependencyChecker(MissingCheckers):
                    self.recommend_python = True

                progs.update({
-                    "python-sphinx": "python311-Sphinx",
+                    "python-sphinx": "python311-Sphinx python311-Sphinx-latex",
                    "virtualenv":    "python311-virtualenv",
                    "yaml":          "python311-PyYAML",
                })
@@ -939,7 +945,7 @@ class SphinxDependencyChecker(MissingCheckers):
            # Tumbleweed defaults to Python 3.11

            progs.update({
-                "python-sphinx": "python313-Sphinx",
+                "python-sphinx": "python313-Sphinx python313-Sphinx-latex",
                "virtualenv":    "python313-virtualenv",
                "yaml":          "python313-PyYAML",
            })
@@ -973,18 +979,26 @@ class SphinxDependencyChecker(MissingCheckers):

        tex_pkgs = [
            "texlive-fontsextra",
+            "texlive-fonts-asian",
+            "fonts-ttf-dejavu",
        ]

        if re.search(r"OpenMandriva", self.system_release):
            packager_cmd = "dnf install"
            noto_sans = "noto-sans-cjk-fonts"
-            tex_pkgs = ["texlive-collection-fontsextra"]
+            tex_pkgs = [
+                "texlive-collection-basic",
+                "texlive-collection-langcjk",
+                "texlive-collection-fontsextra",
+                "texlive-collection-fontsrecommended"
+            ]

            # Tested on OpenMandriva Lx 4.3
            progs["convert"] = "imagemagick"
            progs["yaml"] = "python-pyyaml"
            progs["python-virtualenv"] = "python-virtualenv"
            progs["python-sphinx"] = "python-sphinx"
+            progs["xelatex"] = "texlive"

            self.check_program("python-virtualenv", DepManager.PYTHON_MANDATORY)

@@ -998,7 +1012,9 @@ class SphinxDependencyChecker(MissingCheckers):

            if not self.distro_msg:
                self.distro_msg = \
-                    "Note: for venv, ensurepip could be broken, preventing its install method."
+                    "Notes:\n"\
+                    "1. for venv, ensurepip could be broken, preventing its install method.\n" \
+                    "2. at least on OpenMandriva LX 4.3, texlive packages seem broken"

        else:
            packager_cmd = "urpmi"
@@ -1032,7 +1048,12 @@ class SphinxDependencyChecker(MissingCheckers):
        }

        archlinux_tex_pkgs = [
+            "texlive-basic",
+            "texlive-binextra",
            "texlive-core",
+            "texlive-fontsrecommended",
+            "texlive-langchinese",
+            "texlive-langcjk",
            "texlive-latexextra",
            "ttf-dejavu",
        ]
@@ -1052,12 +1073,19 @@ class SphinxDependencyChecker(MissingCheckers):
        """
        Provide package installation hints for Gentoo.
        """
+        texlive_deps = [
+            "dev-texlive/texlive-fontsrecommended",
+            "dev-texlive/texlive-latexextra",
+            "dev-texlive/texlive-xetex",
+            "media-fonts/dejavu",
+        ]
+
        progs = {
            "convert":       "media-gfx/imagemagick",
            "dot":           "media-gfx/graphviz",
            "rsvg-convert":  "gnome-base/librsvg",
            "virtualenv":    "dev-python/virtualenv",
-            "xelatex":       "dev-texlive/texlive-xetex media-fonts/dejavu",
+            "xelatex":       " ".join(texlive_deps),
            "yaml":          "dev-python/pyyaml",
            "python-sphinx": "dev-python/sphinx",
        }