mirror of
https://github.com/u-boot/u-boot.git
synced 2025-05-08 19:11:53 +00:00
doc: update Kernel documentation build system
Update the docomentation build system according to Linux v5.11-rc1. 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> Reviewed-by: Simon Glass <sjg@chromium.org> [Fix warning in b4860qds.rst about "Switch Settings"] Signed-off-by: Tom Rini <trini@konsulko.com>
This commit is contained in:
Heinrich Schuchardt
Tom Rini
parent
4afc4f37c7
commit
10a1df3cd4
15 changed files with 1478 additions and 158 deletions
139
doc/conf.py
139
doc/conf.py
|
|
@ -16,6 +16,8 @@ import sys
|
|||
import os
|
||||
import sphinx
|
||||
|
||||
from subprocess import check_output
|
||||
|
||||
# Get Sphinx version
|
||||
major, minor, patch = sphinx.version_info[:3]
|
||||
|
||||
|
|
@ -31,39 +33,98 @@ from load_config import loadConfig
|
|||
# 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 @@ source_suffix = '.rst'
|
|||
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 @@ except ImportError:
|
|||
|
||||
# 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 @@ html_context = {
|
|||
|
||||
# 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_context = {
|
|||
#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 @@ latex_elements = {
|
|||
'papersize': 'a4paper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
'pointsize': '8pt',
|
||||
'pointsize': '11pt',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#'figure_align': 'htbp',
|
||||
|
|
@ -301,13 +362,24 @@ latex_elements = {
|
|||
'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 @@ if major == 1 and minor < 6:
|
|||
# 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 @@ latex_documents = [
|
|||
# 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 @@ man_pages = [
|
|||
# (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 @@ epub_exclude_files = ['search.html']
|
|||
# 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue