doc: update Kernel documentation build system
Update the documentation build system according to Linux v5.11-rc1.
Deactive the automarkup.py extension module which on Gitlab CI is
incompatible with Unicode.
With this patch we can build the HTML documentation using either of
Sphinx 2 and Sphinx 3.
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
diff --git a/doc/conf.py b/doc/conf.py
index ee7f201..3f456a1 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,6 +16,8 @@
import os
import sphinx
+from subprocess import check_output
+
# Get Sphinx version
major, minor, patch = sphinx.version_info[:3]
@@ -31,39 +33,98 @@
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.3'
-latex_engine = 'xelatex'
-
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'kfigure']
+extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
+ 'kfigure', 'sphinx.ext.ifconfig', # 'automarkup',
+ 'maintainers_include', 'sphinx.ext.autosectionlabel',
+ 'kernel_abi', 'kernel_feat']
#
-# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most*
-# of the docs correctly, but not all.
+# cdomain is badly broken in Sphinx 3+. Leaving it out generates *most*
+# of the docs correctly, but not all. Scream bloody murder but allow
+# the process to proceed; hopefully somebody will fix this properly soon.
#
if major >= 3:
+ sys.stderr.write('''WARNING: The kernel documentation build process
+ support for Sphinx v3.0 and above is brand new. Be prepared for
+ possible issues in the generated output.
+ ''')
if (major > 3) or (minor > 0 or patch >= 2):
- sys.stderr.write('''The build process with Sphinx 3+ is broken.
-You will have to remove -W in doc/Makefile.
-''')
# Sphinx c function parser is more pedantic with regards to type
# checking. Due to that, having macros at c:function cause problems.
- # Those needed to be escaped by using c_id_attributes[] array
+ # Those needed to be scaped by using c_id_attributes[] array
c_id_attributes = [
+ # GCC Compiler types not parsed by Sphinx:
+ "__restrict__",
- # include/linux/compiler.h
+ # include/linux/compiler_types.h:
+ "__iomem",
+ "__kernel",
+ "noinstr",
+ "notrace",
+ "__percpu",
+ "__rcu",
+ "__user",
+
+ # include/linux/compiler_attributes.h:
+ "__alias",
+ "__aligned",
+ "__aligned_largest",
+ "__always_inline",
+ "__assume_aligned",
+ "__cold",
+ "__attribute_const__",
+ "__copy",
+ "__pure",
+ "__designated_init",
+ "__visible",
+ "__printf",
+ "__scanf",
+ "__gnu_inline",
+ "__malloc",
+ "__mode",
+ "__no_caller_saved_registers",
+ "__noclone",
+ "__nonstring",
+ "__noreturn",
+ "__packed",
+ "__pure",
+ "__section",
+ "__always_unused",
"__maybe_unused",
+ "__used",
+ "__weak",
+ "noinline",
# include/efi.h
"EFIAPI",
# include/efi_loader.h
"__efi_runtime",
+
+ # include/linux/memblock.h:
+ "__init_memblock",
+ "__meminit",
+
+ # include/linux/init.h:
+ "__init",
+ "__ref",
+
+ # include/linux/linkage.h:
+ "asmlinkage",
]
else:
extensions.append('cdomain')
+ if major == 1 and minor < 7:
+ sys.stderr.write('WARNING: Sphinx 1.7 or greater will be required as of '
+ 'the v2021.04 release\n')
+
+# Ensure that autosectionlabel will produce unique names
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
# The name of the math extension changed on Sphinx 1.4
if (major == 1 and minor > 3) or (major > 1):
@@ -86,9 +147,9 @@
master_doc = 'index'
# General information about the project.
-project = 'Das U-Boot'
-copyright = 'The U-Boot development community'
-author = 'The U-Boot development community'
+project = 'The Linux Kernel'
+copyright = 'The kernel development community'
+author = 'The kernel development community'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -199,7 +260,7 @@
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
-html_logo = '../tools/logos/u-boot_logo.svg'
+#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -229,7 +290,7 @@
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
-#html_use_smartypants = True
+html_use_smartypants = False
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
@@ -279,7 +340,7 @@
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
-htmlhelp_basename = 'TheUBootdoc'
+htmlhelp_basename = 'TheLinuxKerneldoc'
# -- Options for LaTeX output ---------------------------------------------
@@ -288,7 +349,7 @@
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
-'pointsize': '8pt',
+'pointsize': '11pt',
# Latex figure (float) alignment
#'figure_align': 'htbp',
@@ -301,13 +362,24 @@
'preamble': '''
% Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec}
- \\setsansfont{DejaVu Serif}
- \\setromanfont{DejaVu Sans}
+ \\setsansfont{DejaVu Sans}
+ \\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono}
-
'''
}
+# At least one book (translations) may have Asian characters
+# with are only displayed if xeCJK is used
+
+cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
+if cjk_cmd.find("Noto Sans CJK SC") >= 0:
+ print ("enabling CJK for LaTeX builder")
+ latex_elements['preamble'] += '''
+ % This is needed for translations
+ \\usepackage{xeCJK}
+ \\setCJKmainfont{Noto Sans CJK SC}
+ '''
+
# Fix reference escape troubles with Sphinx 1.4.x
if major == 1 and minor > 3:
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
@@ -398,10 +470,23 @@
# author, documentclass [howto, manual, or own class]).
# Sorted in alphabetical order
latex_documents = [
- ('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual',
- 'The U-Boot development community', 'manual'),
]
+# 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
@@ -428,7 +513,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'dasuboot', 'The U-Boot Documentation',
+ (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
[author], 1)
]
@@ -442,8 +527,8 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- (master_doc, 'DasUBoot', 'The U-Boot Documentation',
- author, 'DasUBoot', 'One line description of project.',
+ (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
+ author, 'TheLinuxKernel', 'One line description of project.',
'Miscellaneous'),
]
@@ -535,13 +620,13 @@
# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
-# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
+# 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 = [
- ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'),
+ ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
]
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read