summaryrefslogtreecommitdiff
path: root/Documentation/conf.py
diff options
context:
space:
mode:
authorAkira Yokosawa <akiyks@gmail.com>2022-02-18 23:11:17 +0900
committerJonathan Corbet <corbet@lwn.net>2022-02-24 12:26:13 -0700
commit398f7abdcb7e2307facebcbdae5639f7d35916cd (patch)
tree678adde9b3b4b4394d5095e1e417396a44696293 /Documentation/conf.py
parentb089f167c384c7ca0adc50c78dd7a98f747d5e03 (diff)
downloadlwn-398f7abdcb7e2307facebcbdae5639f7d35916cd.tar.gz
lwn-398f7abdcb7e2307facebcbdae5639f7d35916cd.zip
docs: pdfdocs: Pull LaTeX preamble part out of conf.py
Quote from Jon's remark [1]: I do notice that Documentation/conf.py is getting large and unapproachable. At some future point, it might be nice to pull all of the latex stuff out into a separate file where it won't scare people who stumble into it by accident. Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs: conf.py: adjust the LaTeX document output") out into sphinx/kerneldoc-preamble.sty. It will be copied to the build directory by the added "latex_additional_files" setting in conf.py. As a bonus, LaTeX/TeX code can be maintained without escaping backslashes. To compensate the loss of change history in sphinx/kerneldoc-preamble.sty, here is a list of changes made in conf.py: - f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters") - 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary") - 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document") - e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings") - 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible") - 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations") - 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations") - 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts") - 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks") - 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings") - aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr") - 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC") - 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants") - 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles") - 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found") - b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py") [1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/ Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/conf.py')
-rw-r--r--Documentation/conf.py184
1 files changed, 13 insertions, 171 deletions
diff --git a/Documentation/conf.py b/Documentation/conf.py
index fb8f69fc4d38..072ee31a301d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -409,188 +409,25 @@ latex_elements = {
# Additional stuff for the LaTeX preamble.
'preamble': '''
- % Custom width parameters for TOC --- Redefine low-level commands
- % defined in report.cls
- \\makeatletter
- %% Redefine \\@pnumwidth (page number width)
- \\renewcommand*\\@pnumwidth{2.7em}
- %% Redefine \\l@chapter (chapter list entry)
- \\renewcommand*\\l@chapter[2]{%
- \\ifnum \\c@tocdepth >\\m@ne
- \\addpenalty{-\\@highpenalty}%
- \\vskip 1.0em \\@plus\\p@
- \\setlength\\@tempdima{1.8em}%
- \\begingroup
- \\parindent \\z@ \\rightskip \\@pnumwidth
- \\parfillskip -\\@pnumwidth
- \\leavevmode \\bfseries
- \\advance\\leftskip\\@tempdima
- \\hskip -\\leftskip
- #1\\nobreak\\hfil
- \\nobreak\\hb@xt@\\@pnumwidth{\\hss #2%
- \\kern-\\p@\\kern\\p@}\\par
- \\penalty\\@highpenalty
- \\endgroup
- \\fi}
- %% Redefine \\l@section and \\l@subsection
- \\renewcommand*\\l@section{\\@dottedtocline{1}{1.8em}{3.2em}}
- \\renewcommand*\\l@subsection{\\@dottedtocline{2}{5em}{4.3em}}
- \\makeatother
- %% Sphinx < 1.8 doesn't have \\sphinxtableofcontentshook
- \\providecommand{\\sphinxtableofcontentshook}{}
- %% Undefine it for compatibility with Sphinx 1.7.9
- \\renewcommand{\\sphinxtableofcontentshook}{} % Empty the hook
- % Prevent column squeezing of tabulary.
- \\setlength{\\tymin}{20em}
% Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec}
\\setsansfont{DejaVu Sans}
\\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono}
- % Adjust \\headheight for fancyhdr
- \\addtolength{\\headheight}{1.6pt}
- \\addtolength{\\topmargin}{-1.6pt}
- ''',
+ ''',
}
-# Translations have Asian (CJK) characters which are only displayed if
-# xeCJK is used
-
-latex_elements['preamble'] += '''
- \\IfFontExistsTF{Noto Sans CJK SC}{
- % This is needed for translations
- \\usepackage{xeCJK}
- \\IfFontExistsTF{Noto Serif CJK KR}{
- \\setCJKmainfont{Noto Serif CJK KR}[AutoFakeSlant]
- }{
- \\setCJKmainfont{Noto Sans CJK KR}[AutoFakeSlant]
- }
- \\setCJKsansfont{Noto Sans CJK KR}[AutoFakeSlant]
- \\setCJKmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]
- \\xeCJKDeclareCharClass{HalfLeft}{`“,`‘}
- \\xeCJKDeclareCharClass{HalfRight}{`”,`’}
- % CJK Language-specific font choices
- \\IfFontExistsTF{Noto Serif CJK SC}{
- \\newCJKfontfamily[SCmain]\\scmain{Noto Serif CJK SC}[AutoFakeSlant]
- \\newCJKfontfamily[SCserif]\\scserif{Noto Serif CJK SC}[AutoFakeSlant]
- }{
- \\newCJKfontfamily[SCmain]\\scmain{Noto Sans CJK SC}[AutoFakeSlant]
- \\newCJKfontfamily[SCserif]\\scserif{Noto Sans CJK SC}[AutoFakeSlant]
- }
- \\newCJKfontfamily[SCsans]\\scsans{Noto Sans CJK SC}[AutoFakeSlant]
- \\newCJKfontfamily[SCmono]\\scmono{Noto Sans Mono CJK SC}[AutoFakeSlant]
- \\IfFontExistsTF{Noto Serif CJK TC}{
- \\newCJKfontfamily[TCmain]\\tcmain{Noto Serif CJK TC}[AutoFakeSlant]
- \\newCJKfontfamily[TCserif]\\tcserif{Noto Serif CJK TC}[AutoFakeSlant]
- }{
- \\newCJKfontfamily[TCmain]\\tcmain{Noto Sans CJK TC}[AutoFakeSlant]
- \\newCJKfontfamily[TCserif]\\tcserif{Noto Sans CJK TC}[AutoFakeSlant]
- }
- \\newCJKfontfamily[TCsans]\\tcsans{Noto Sans CJK TC}[AutoFakeSlant]
- \\newCJKfontfamily[TCmono]\\tcmono{Noto Sans Mono CJK TC}[AutoFakeSlant]
- \\IfFontExistsTF{Noto Serif CJK KR}{
- \\newCJKfontfamily[KRmain]\\krmain{Noto Serif CJK KR}[AutoFakeSlant]
- \\newCJKfontfamily[KRserif]\\krserif{Noto Serif CJK KR}[AutoFakeSlant]
- }{
- \\newCJKfontfamily[KRmain]\\krmain{Noto Sans CJK KR}[AutoFakeSlant]
- \\newCJKfontfamily[KRserif]\\krserif{Noto Sans CJK KR}[AutoFakeSlant]
- }
- \\newCJKfontfamily[KRsans]\\krsans{Noto Sans CJK KR}[AutoFakeSlant]
- \\newCJKfontfamily[KRmono]\\krmono{Noto Sans Mono CJK KR}[AutoFakeSlant]
- \\IfFontExistsTF{Noto Serif CJK JP}{
- \\newCJKfontfamily[JPmain]\\jpmain{Noto Serif CJK JP}[AutoFakeSlant]
- \\newCJKfontfamily[JPserif]\\jpserif{Noto Serif CJK JP}[AutoFakeSlant]
- }{
- \\newCJKfontfamily[JPmain]\\jpmain{Noto Sans CJK JP}[AutoFakeSlant]
- \\newCJKfontfamily[JPserif]\\jpserif{Noto Sans CJK JP}[AutoFakeSlant]
- }
- \\newCJKfontfamily[JPsans]\\jpsans{Noto Sans CJK JP}[AutoFakeSlant]
- \\newCJKfontfamily[JPmono]\\jpmono{Noto Sans Mono CJK JP}[AutoFakeSlant]
- % Dummy commands for Sphinx < 2.3 (no 'extrapackages' support)
- \\providecommand{\\onehalfspacing}{}
- \\providecommand{\\singlespacing}{}
- % Define custom macros to on/off CJK
- \\newcommand{\\kerneldocCJKon}{\\makexeCJKactive\\onehalfspacing}
- \\newcommand{\\kerneldocCJKoff}{\\makexeCJKinactive\\singlespacing}
- \\newcommand{\\kerneldocBeginSC}{%
- \\begingroup%
- \\scmain%
- \\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
- \\xeCJKDeclareCharClass{FullRight}{`”,`’}%
- \\renewcommand{\\CJKrmdefault}{SCserif}%
- \\renewcommand{\\CJKsfdefault}{SCsans}%
- \\renewcommand{\\CJKttdefault}{SCmono}%
- \\xeCJKsetup{CJKspace = false}%
- % For CJK ascii-art alignment
- \\setmonofont{Noto Sans Mono CJK SC}[AutoFakeSlant]%
- }
- \\newcommand{\\kerneldocEndSC}{\\endgroup}
- \\newcommand{\\kerneldocBeginTC}{%
- \\begingroup%
- \\tcmain%
- \\xeCJKDeclareCharClass{FullLeft}{`“,`‘}%
- \\xeCJKDeclareCharClass{FullRight}{`”,`’}%
- \\renewcommand{\\CJKrmdefault}{TCserif}%
- \\renewcommand{\\CJKsfdefault}{TCsans}%
- \\renewcommand{\\CJKttdefault}{TCmono}%
- \\xeCJKsetup{CJKspace = false}%
- % For CJK ascii-art alignment
- \\setmonofont{Noto Sans Mono CJK TC}[AutoFakeSlant]%
- }
- \\newcommand{\\kerneldocEndTC}{\\endgroup}
- \\newcommand{\\kerneldocBeginKR}{%
- \\begingroup%
- \\krmain%
- \\renewcommand{\\CJKrmdefault}{KRserif}%
- \\renewcommand{\\CJKsfdefault}{KRsans}%
- \\renewcommand{\\CJKttdefault}{KRmono}%
- % \\xeCJKsetup{CJKspace = true} % true by default
- % For CJK ascii-art alignment (still misaligned for Hangul)
- \\setmonofont{Noto Sans Mono CJK KR}[AutoFakeSlant]%
- }
- \\newcommand{\\kerneldocEndKR}{\\endgroup}
- \\newcommand{\\kerneldocBeginJP}{%
- \\begingroup%
- \\jpmain%
- \\renewcommand{\\CJKrmdefault}{JPserif}%
- \\renewcommand{\\CJKsfdefault}{JPsans}%
- \\renewcommand{\\CJKttdefault}{JPmono}%
- \\xeCJKsetup{CJKspace = false}%
- % For CJK ascii-art alignment
- \\setmonofont{Noto Sans Mono CJK JP}[AutoFakeSlant]%
- }
- \\newcommand{\\kerneldocEndJP}{\\endgroup}
- % Single spacing in literal blocks
- \\fvset{baselinestretch=1}
- % To customize \\sphinxtableofcontents
- \\usepackage{etoolbox}
- % Inactivate CJK after tableofcontents
- \\apptocmd{\\sphinxtableofcontents}{\\kerneldocCJKoff}{}{}
- \\xeCJKsetup{CJKspace = true} % For inter-phrase space of Korean TOC
- }{ % No CJK font found
- % Custom macros to on/off CJK (Dummy)
- \\newcommand{\\kerneldocCJKon}{}
- \\newcommand{\\kerneldocCJKoff}{}
- \\newcommand{\\kerneldocBeginSC}[1]{%
- \\begin{sphinxadmonition}{note}{Note:}
- ``Noto Sans CJK'' fonts are not found while building this PDF\\@.
- Translations of zh\\_CN, zh\\_TW, ko\\_KR, and ja\\_JP are
- skipped.
- \\end{sphinxadmonition}}
- \\newcommand{\\kerneldocEndSC}{}
- \\newcommand{\\kerneldocBeginTC}[1]{}
- \\newcommand{\\kerneldocEndTC}{}
- \\newcommand{\\kerneldocBeginKR}[1]{}
- \\newcommand{\\kerneldocEndKR}{}
- \\newcommand{\\kerneldocBeginJP}[1]{}
- \\newcommand{\\kerneldocEndJP}{}
- }
-'''
-
# Fix reference escape troubles with Sphinx 1.4.x
if major == 1:
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
+
+# Load kerneldoc specific LaTeX settings
+latex_elements['preamble'] += '''
+ % Load kerneldoc specific LaTeX settings
+ \\input{kerneldoc-preamble.sty}
+'''
+
# With Sphinx 1.6, it is possible to change the Bg color directly
# by using:
# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
@@ -652,6 +489,11 @@ for fn in os.listdir('.'):
# If false, no module index is generated.
#latex_domain_indices = True
+# Additional LaTeX stuff to be copied to build directory
+latex_additional_files = [
+ 'sphinx/kerneldoc-preamble.sty',
+]
+
# -- Options for manual page output ---------------------------------------