change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/conf.py
..
..
@@ -16,6 +16,8 @@
16
16
 import os
17
17
 import sphinx
18
18
 
19
+from subprocess import check_output
20
+
19
21
 # Get Sphinx version
20
22
 major, minor, patch = sphinx.version_info[:3]
21
23
 
..
..
@@ -34,7 +36,86 @@
34
36
 # Add any Sphinx extension module names here, as strings. They can be
35
37
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
36
38
 # ones.
37
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig']
39
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
40
+              'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
41
+              'maintainers_include', 'sphinx.ext.autosectionlabel',
42
+              'kernel_abi']
43
+
44
+#
45
+# cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
46
+# of the docs correctly, but not all.  Scream bloody murder but allow
47
+# the process to proceed; hopefully somebody will fix this properly soon.
48
+#
49
+if major >= 3:
50
+    sys.stderr.write('''WARNING: The kernel documentation build process
51
+        support for Sphinx v3.0 and above is brand new. Be prepared for
52
+        possible issues in the generated output.
53
+        ''')
54
+    if (major > 3) or (minor > 0 or patch >= 2):
55
+        # Sphinx c function parser is more pedantic with regards to type
56
+        # checking. Due to that, having macros at c:function cause problems.
57
+        # Those needed to be scaped by using c_id_attributes[] array
58
+        c_id_attributes = [
59
+            # GCC Compiler types not parsed by Sphinx:
60
+            "__restrict__",
61
+
62
+            # include/linux/compiler_types.h:
63
+            "__iomem",
64
+            "__kernel",
65
+            "noinstr",
66
+            "notrace",
67
+            "__percpu",
68
+            "__rcu",
69
+            "__user",
70
+
71
+            # include/linux/compiler_attributes.h:
72
+            "__alias",
73
+            "__aligned",
74
+            "__aligned_largest",
75
+            "__always_inline",
76
+            "__assume_aligned",
77
+            "__cold",
78
+            "__attribute_const__",
79
+            "__copy",
80
+            "__pure",
81
+            "__designated_init",
82
+            "__visible",
83
+            "__printf",
84
+            "__scanf",
85
+            "__gnu_inline",
86
+            "__malloc",
87
+            "__mode",
88
+            "__no_caller_saved_registers",
89
+            "__noclone",
90
+            "__nonstring",
91
+            "__noreturn",
92
+            "__packed",
93
+            "__pure",
94
+            "__section",
95
+            "__always_unused",
96
+            "__maybe_unused",
97
+            "__used",
98
+            "__weak",
99
+            "noinline",
100
+
101
+            # include/linux/memblock.h:
102
+            "__init_memblock",
103
+            "__meminit",
104
+
105
+            # include/linux/init.h:
106
+            "__init",
107
+            "__ref",
108
+
109
+            # include/linux/linkage.h:
110
+            "asmlinkage",
111
+        ]
112
+
113
+else:
114
+    extensions.append('cdomain')
115
+
116
+# Ensure that autosectionlabel will produce unique names
117
+autosectionlabel_prefix_document = True
118
+autosectionlabel_maxdepth = 2
38
119
 
39
120
 # The name of the math extension changed on Sphinx 1.4
40
121
 if (major == 1 and minor > 3) or (major > 1):
..
..
@@ -95,7 +176,7 @@
95
176
 #
96
177
 # This is also used if you do content translation via gettext catalogs.
97
178
 # Usually you set "language" from the command line for these cases.
98
-language = None
179
+language = 'en'
99
180
 
100
181
 # There are two options for replacing |today|: either, you set today to some
101
182
 # non-false value, then it is used:
..
..
@@ -200,7 +281,7 @@
200
281
 
201
282
 # If true, SmartyPants will be used to convert quotes and dashes to
202
283
 # typographically correct entities.
203
-#html_use_smartypants = True
284
+html_use_smartypants = False
204
285
 
205
286
 # Custom sidebar templates, maps document names to template names.
206
287
 #html_sidebars = {}
..
..
@@ -259,7 +340,7 @@
259
340
 'papersize': 'a4paper',
260
341
 
261
342
 # The font size ('10pt', '11pt' or '12pt').
262
-'pointsize': '8pt',
343
+'pointsize': '11pt',
263
344
 
264
345
 # Latex figure (float) alignment
265
346
 #'figure_align': 'htbp',
..
..
@@ -272,12 +353,23 @@
272
353
     'preamble': '''
273
354
 	% Use some font with UTF-8 support with XeLaTeX
274
355
         \\usepackage{fontspec}
275
-        \\setsansfont{DejaVu Serif}
276
-        \\setromanfont{DejaVu Sans}
356
+        \\setsansfont{DejaVu Sans}
357
+        \\setromanfont{DejaVu Serif}
277
358
         \\setmonofont{DejaVu Sans Mono}
278
-
279
359
      '''
280
360
 }
361
+
362
+# At least one book (translations) may have Asian characters
363
+# with are only displayed if xeCJK is used
364
+
365
+cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
366
+if cjk_cmd.find("Noto Sans CJK SC") >= 0:
367
+    print ("enabling CJK for LaTeX builder")
368
+    latex_elements['preamble']  += '''
369
+	% This is needed for translations
370
+        \\usepackage{xeCJK}
371
+        \\setCJKmainfont{Noto Sans CJK SC}
372
+     '''
281
373
 
282
374
 # Fix reference escape troubles with Sphinx 1.4.x
283
375
 if major == 1 and minor > 3:
..
..
@@ -369,41 +461,22 @@
369
461
 #  author, documentclass [howto, manual, or own class]).
370
462
 # Sorted in alphabetical order
371
463
 latex_documents = [
372
-    ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
373
-     'The kernel development community', 'manual'),
374
-    ('core-api/index', 'core-api.tex', 'The kernel core API manual',
375
-     'The kernel development community', 'manual'),
376
-    ('crypto/index', 'crypto-api.tex', 'Linux Kernel Crypto API manual',
377
-     'The kernel development community', 'manual'),
378
-    ('dev-tools/index', 'dev-tools.tex', 'Development tools for the Kernel',
379
-     'The kernel development community', 'manual'),
380
-    ('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
381
-     'The kernel development community', 'manual'),
382
-    ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
383
-     'The kernel development community', 'manual'),
384
-    ('filesystems/index', 'filesystems.tex', 'Linux Filesystems API',
385
-     'The kernel development community', 'manual'),
386
-    ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
387
-     'The kernel development community', 'manual'),
388
-    ('input/index', 'linux-input.tex', 'The Linux input driver subsystem',
389
-     'The kernel development community', 'manual'),
390
-    ('kernel-hacking/index', 'kernel-hacking.tex', 'Unreliable Guide To Hacking The Linux Kernel',
391
-     'The kernel development community', 'manual'),
392
-    ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
393
-     'The kernel development community', 'manual'),
394
-    ('networking/index', 'networking.tex', 'Linux Networking Documentation',
395
-     'The kernel development community', 'manual'),
396
-    ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
397
-     'The kernel development community', 'manual'),
398
-    ('security/index', 'security.tex', 'The kernel security subsystem manual',
399
-     'The kernel development community', 'manual'),
400
-    ('sh/index', 'sh.tex', 'SuperH architecture implementation manual',
401
-     'The kernel development community', 'manual'),
402
-    ('sound/index', 'sound.tex', 'Linux Sound Subsystem Documentation',
403
-     'The kernel development community', 'manual'),
404
-    ('userspace-api/index', 'userspace-api.tex', 'The Linux kernel user-space API guide',
405
-     'The kernel development community', 'manual'),
406
464
 ]
465
+
466
+# Add all other index files from Documentation/ subdirectories
467
+for fn in os.listdir('.'):
468
+    doc = os.path.join(fn, "index")
469
+    if os.path.exists(doc + ".rst"):
470
+        has = False
471
+        for l in latex_documents:
472
+            if l[0] == doc:
473
+                has = True
474
+                break
475
+        if not has:
476
+            latex_documents.append((doc, fn + '.tex',
477
+                                    'Linux %s Documentation' % fn.capitalize(),
478
+                                    'The kernel development community',
479
+                                    'manual'))
407
480
 
408
481
 # The name of an image file (relative to this directory) to place at the top of
409
482
 # the title page.
..
..
@@ -538,7 +611,7 @@
538
611
 # Grouping the document tree into PDF files. List of tuples
539
612
 # (source start file, target name, title, author, options).
540
613
 #
541
-# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
614
+# See the Sphinx chapter of https://ralsina.me/static/manual.pdf
542
615
 #
543
616
 # FIXME: Do not add the index file here; the result will be too big. Adding
544
617
 # multiple PDF files here actually tries to get the cross-referencing right