diff --git a/Documentation/Makefile b/Documentation/Makefile index 820f07e0afe6..2ed334971acd 100644 --- 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),) diff --git a/Documentation/conf.py b/Documentation/conf.py index 856c04a2abb7..8fcecdb927b1 100644 --- 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) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index b8474848df4e..954ed3dc0645 100755 --- 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", }