[mirror_ubuntu-jammy-kernel.git] / Documentation / conf.py

# -*- coding: utf-8 -*-
#
# The Linux Kernel documentation build configuration file, created by
# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

import sys
import os
import sphinx

from subprocess import check_output

# Get Sphinx version
major, minor, patch = sphinx.version_info[:3]


# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('sphinx'))
from load_config import loadConfig

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.7'

# 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', '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.  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.\n''')
    if (major > 3) or (minor > 0 or patch >= 2):
        # 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 scaped by using c_id_attributes[] array
        c_id_attributes = [
            # GCC Compiler types not parsed by Sphinx:
            "__restrict__",

            # 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/linux/memblock.h:
            "__init_memblock",
            "__meminit",

            # include/linux/init.h:
            "__init",
            "__ref",

            # include/linux/linkage.h:
            "asmlinkage",
        ]

else:
    extensions.append('cdomain')

# Ensure that autosectionlabel will produce unique names
autosectionlabel_prefix_document = True
autosectionlabel_maxdepth = 2

extensions.append("sphinx.ext.imgmath")

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#source_encoding = 'utf-8-sig'

# The master toctree document.
master_doc = 'index'

# General information about the project.
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
# built documents.
#
# In a normal build, version and release are are set to KERNELVERSION and
# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
# arguments.
#
# The following code tries to extract the information by reading the Makefile,
# when Sphinx is run directly (e.g. by Read the Docs).
try:
    makefile_version = None
    makefile_patchlevel = None
    for line in open('../Makefile'):
        key, val = [x.strip() for x in line.split('=', 2)]
        if key == 'VERSION':
            makefile_version = val
        elif key == 'PATCHLEVEL':
            makefile_patchlevel = val
        if makefile_version and makefile_patchlevel:
            break
except:
    pass
finally:
    if makefile_version and makefile_patchlevel:
        version = release = makefile_version + '.' + makefile_patchlevel
    else:
        version = release = "unknown version"

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['output']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False

primary_domain = 'c'
highlight_language = 'none'

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.

# The Read the Docs theme is available from
# - https://github.com/snide/sphinx_rtd_theme
# - https://pypi.python.org/pypi/sphinx_rtd_theme
# - python-sphinx-rtd-theme package (on Debian)
try:
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
except ImportError:
    sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []

# The name for this set of Sphinx documents.  If None, it defaults to
# "<project> v<release> documentation".
#html_title = None

# A shorter title for the navigation bar.  Default is the same as html_title.
#html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#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
# pixels large.
#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".

html_static_path = ['sphinx-static']

html_context = {
    'css_files': [
        '_static/theme_overrides.css',
    ],
}

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = False

# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}

# If false, no module index is generated.
#html_domain_indices = True

# If false, no index is generated.
#html_use_index = True

# If true, the index is split into individual pages for each letter.
#html_split_index = False

# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
#html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'TheLinuxKerneldoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    'papersize': 'a4paper',

    # The font size ('10pt', '11pt' or '12pt').
    'pointsize': '11pt',

    # Latex figure (float) alignment
    #'figure_align': 'htbp',

    # Don't mangle with UTF-8 chars
    'inputenc': '',
    'utf8extra': '',

    # Set document margins
    'sphinxsetup': '''
        hmargin=0.5in, vmargin=1in,
        parsedliteralwraps=true,
        verbatimhintsturnover=false,
    ''',

    # 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}
     ''',
}

# 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:
    latex_elements['preamble']  += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'

# With Sphinx 1.6, it is possible to change the Bg color directly
# by using:
#	\definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
#	\definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
#	\definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
#	\definecolor{sphinximportantBgColor}{RGB}{192,255,204}
#
# However, it require to use sphinx heavy box with:
#
#	\renewenvironment{sphinxlightbox} {%
#		\\begin{sphinxheavybox}
#	}
#		\\end{sphinxheavybox}
#	}
#
# Unfortunately, the implementation is buggy: if a note is inside a
# table, it isn't displayed well. So, for now, let's use boring
# black and white notes.

# 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
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

# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False

# If true, show page references after internal links.
#latex_show_pagerefs = False

# If true, show URL addresses after external links.
#latex_show_urls = False

# Documents to append as an appendix to all manuals.
#latex_appendices = []

# If false, no module index is generated.
#latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
     author, 'TheLinuxKernel', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#texinfo_appendices = []

# If false, no module index is generated.
#texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False


# -- Options for Epub output ----------------------------------------------

# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright

# The basename for the epub file. It defaults to the project name.
#epub_basename = project

# The HTML theme for the epub output. Since the default themes are not
# optimized for small screen space, using the same theme for HTML and epub
# output is usually not wise. This defaults to 'epub', a theme designed to save
# visual space.
#epub_theme = 'epub'

# The language of the text. It defaults to the language option
# or 'en' if the language is not set.
#epub_language = ''

# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''

# A unique identification for the text.
#epub_uid = ''

# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()

# A sequence of (type, uri, title) tuples for the guide element of content.opf.
#epub_guide = ()

# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []

# HTML files that should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []

# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']

# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3

# Allow duplicate toc entries.
#epub_tocdup = True

# Choose between 'default' and 'includehidden'.
#epub_tocscope = 'default'

# Fix unsupported image types using the Pillow.
#epub_fix_images = False

# Scale large images.
#epub_max_image_width = 0

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'

# If false, no index is generated.
#epub_use_index = True

#=======
# rst2pdf
#
# Grouping the document tree into PDF files. List of tuples
# (source start file, target name, title, author, options).
#
# 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 = [
    ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
]

# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
# the Docs). In a normal build, these are supplied from the Makefile via command
# line arguments.
kerneldoc_bin = '../scripts/kernel-doc'
kerneldoc_srctree = '..'

# ------------------------------------------------------------------------------
# Since loadConfig overwrites settings from the global namespace, it has to be
# the last statement in the conf.py file
# ------------------------------------------------------------------------------
loadConfig(globals())
Commit	Line	Data
22cba31b JN	1	# -- coding: utf-8 --
	2	#
	3	# The Linux Kernel documentation build configuration file, created by
	4	# sphinx-quickstart on Fri Feb 12 13:51:46 2016.
	5	#
	6	# This file is execfile()d with the current directory set to its
	7	# containing dir.
	8	#
	9	# Note that not all possible configuration values are present in this
	10	# autogenerated file.
	11	#
	12	# All configuration values have a default; values that are commented out
	13	# serve to show the default.
	14
	15	import sys
	16	import os
d4fe7e14 MCC	17	import sphinx
d4fe7e14 MCC	18
e0de2b59 MCC	19	from subprocess import check_output
e0de2b59 MCC	20
d4fe7e14	21	# Get Sphinx version
c46988ae	22	major, minor, patch = sphinx.version_info[:3]
d4fe7e14	23
22cba31b JN	24
	25	# If extensions (or modules to document with autodoc) are in another directory,
	26	# add these directories to sys.path here. If the directory is relative to the
	27	# documentation root, use os.path.abspath to make it absolute, like shown here.
24dcdeb2	28	sys.path.insert(0, os.path.abspath('sphinx'))
606b9ac8	29	from load_config import loadConfig
22cba31b JN	30
	31	# -- General configuration ------------------------------------------------
	32
	33	# If your documentation needs a minimal Sphinx version, state it here.
f546ff0c	34	needs_sphinx = '1.7'
22cba31b JN	35
	36	# Add any Sphinx extension module names here, as strings. They can be
	37	# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
	38	# ones.
afde706a	39	extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
aa204855	40	'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
a7ee04b3	41	'maintainers_include', 'sphinx.ext.autosectionlabel',
63fdc462	42	'kernel_abi', 'kernel_feat']
22cba31b	43
afde706a JC	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
14059a38	51	support for Sphinx v3.0 and above is brand new. Be prepared for
36d8900d	52	possible issues in the generated output.\n''')
d29f34c0	53	if (major > 3) or (minor > 0 or patch >= 2):
b34b86d7 MCC	54	# Sphinx c function parser is more pedantic with regards to type
	55	# checking. Due to that, having macros at c:function cause problems.
	56	# Those needed to be scaped by using c_id_attributes[] array
	57	c_id_attributes = [
	58	# GCC Compiler types not parsed by Sphinx:
	59	"__restrict__",
	60
	61	# include/linux/compiler_types.h:
	62	"__iomem",
	63	"__kernel",
	64	"noinstr",
	65	"notrace",
	66	"__percpu",
	67	"__rcu",
	68	"__user",
	69
	70	# include/linux/compiler_attributes.h:
	71	"__alias",
	72	"__aligned",
	73	"__aligned_largest",
	74	"__always_inline",
	75	"__assume_aligned",
	76	"__cold",
	77	"__attribute_const__",
	78	"__copy",
	79	"__pure",
	80	"__designated_init",
	81	"__visible",
	82	"__printf",
	83	"__scanf",
	84	"__gnu_inline",
	85	"__malloc",
	86	"__mode",
	87	"__no_caller_saved_registers",
	88	"__noclone",
	89	"__nonstring",
	90	"__noreturn",
	91	"__packed",
	92	"__pure",
	93	"__section",
	94	"__always_unused",
	95	"__maybe_unused",
	96	"__used",
	97	"__weak",
	98	"noinline",
	99
	100	# include/linux/memblock.h:
	101	"__init_memblock",
	102	"__meminit",
	103
	104	# include/linux/init.h:
	105	"__init",
	106	"__ref",
	107
	108	# include/linux/linkage.h:
	109	"asmlinkage",
	110	]
	111
afde706a JC	112	else:
	113	extensions.append('cdomain')
	114
4658b0eb MCC	115	# Ensure that autosectionlabel will produce unique names
	116	autosectionlabel_prefix_document = True
	117	autosectionlabel_maxdepth = 2
	118
f546ff0c	119	extensions.append("sphinx.ext.imgmath")
22cba31b JN	120
	121	# Add any paths that contain templates here, relative to this directory.
	122	templates_path = ['_templates']
	123
	124	# The suffix(es) of source filenames.
	125	# You can specify multiple suffix as a list of string:
	126	# source_suffix = ['.rst', '.md']
	127	source_suffix = '.rst'
	128
	129	# The encoding of source files.
	130	#source_encoding = 'utf-8-sig'
	131
	132	# The master toctree document.
	133	master_doc = 'index'
	134
	135	# General information about the project.
	136	project = 'The Linux Kernel'
dc36143f	137	copyright = 'The kernel development community'
22cba31b JN	138	author = 'The kernel development community'
	139
	140	# The version info for the project you're documenting, acts as replacement for
	141	# \|version\| and \|release\|, also used in various other places throughout the
	142	# built documents.
	143	#
c13ce448 JN	144	# In a normal build, version and release are are set to KERNELVERSION and
	145	# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
	146	# arguments.
	147	#
	148	# The following code tries to extract the information by reading the Makefile,
	149	# when Sphinx is run directly (e.g. by Read the Docs).
	150	try:
	151	makefile_version = None
	152	makefile_patchlevel = None
	153	for line in open('../Makefile'):
	154	key, val = [x.strip() for x in line.split('=', 2)]
	155	if key == 'VERSION':
	156	makefile_version = val
	157	elif key == 'PATCHLEVEL':
	158	makefile_patchlevel = val
	159	if makefile_version and makefile_patchlevel:
	160	break
	161	except:
	162	pass
	163	finally:
	164	if makefile_version and makefile_patchlevel:
	165	version = release = makefile_version + '.' + makefile_patchlevel
	166	else:
c13ce448	167	version = release = "unknown version"
22cba31b JN	168
	169	# The language for content autogenerated by Sphinx. Refer to documentation
	170	# for a list of supported languages.
	171	#
	172	# This is also used if you do content translation via gettext catalogs.
	173	# Usually you set "language" from the command line for these cases.
	174	language = None
	175
	176	# There are two options for replacing \|today\|: either, you set today to some
	177	# non-false value, then it is used:
	178	#today = ''
	179	# Else, today_fmt is used as the format for a strftime call.
	180	#today_fmt = '%B %d, %Y'
	181
	182	# List of patterns, relative to source directory, that match files and
	183	# directories to ignore when looking for source files.
	184	exclude_patterns = ['output']
	185
	186	# The reST default role (used for this markup: `text`) to use for all
	187	# documents.
	188	#default_role = None
	189
	190	# If true, '()' will be appended to :func: etc. cross-reference text.
	191	#add_function_parentheses = True
	192
	193	# If true, the current module name will be prepended to all description
	194	# unit titles (such as .. function::).
	195	#add_module_names = True
	196
	197	# If true, sectionauthor and moduleauthor directives will be shown in the
	198	# output. They are ignored by default.
	199	#show_authors = False
	200
	201	# The name of the Pygments (syntax highlighting) style to use.
	202	pygments_style = 'sphinx'
	203
	204	# A list of ignored prefixes for module index sorting.
	205	#modindex_common_prefix = []
	206
	207	# If true, keep warnings as "system message" paragraphs in the built documents.
	208	#keep_warnings = False
	209
	210	# If true, `todo` and `todoList` produce output, else they produce nothing.
	211	todo_include_todos = False
	212
fd5d6669	213	primary_domain = 'c'
b459106e	214	highlight_language = 'none'
22cba31b JN	215
	216	# -- Options for HTML output ----------------------------------------------
	217
	218	# The theme to use for HTML and HTML Help pages. See the documentation for
	219	# a list of builtin themes.
	220
	221	# The Read the Docs theme is available from
	222	# - https://github.com/snide/sphinx_rtd_theme
	223	# - https://pypi.python.org/pypi/sphinx_rtd_theme
	224	# - python-sphinx-rtd-theme package (on Debian)
	225	try:
	226	import sphinx_rtd_theme
	227	html_theme = 'sphinx_rtd_theme'
	228	html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
	229	except ImportError:
	230	sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme.\n')
	231
	232	# Theme options are theme-specific and customize the look and feel of a theme
	233	# further. For a list of options available for each theme, see the
	234	# documentation.
	235	#html_theme_options = {}
	236
	237	# Add any paths that contain custom themes here, relative to this directory.
	238	#html_theme_path = []
	239
	240	# The name for this set of Sphinx documents. If None, it defaults to
	241	# "<project> v<release> documentation".
	242	#html_title = None
	243
	244	# A shorter title for the navigation bar. Default is the same as html_title.
	245	#html_short_title = None
	246
	247	# The name of an image file (relative to this directory) to place at the top
	248	# of the sidebar.
	249	#html_logo = None
	250
	251	# The name of an image file (within the static path) to use as favicon of the
	252	# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
	253	# pixels large.
	254	#html_favicon = None
	255
	256	# Add any paths that contain custom static files (such as style sheets) here,
	257	# relative to this directory. They are copied after the builtin static files,
	258	# so a file named "default.css" will overwrite the builtin "default.css".
bc214671 MH	259
	260	html_static_path = ['sphinx-static']
	261
	262	html_context = {
	263	'css_files': [
	264	'_static/theme_overrides.css',
	265	],
	266	}
22cba31b JN	267
	268	# Add any extra paths that contain custom files (such as robots.txt or
	269	# .htaccess) here, relative to this directory. These files are copied
	270	# directly to the root of the documentation.
	271	#html_extra_path = []
	272
	273	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
	274	# using the given strftime format.
	275	#html_last_updated_fmt = '%b %d, %Y'
	276
	277	# If true, SmartyPants will be used to convert quotes and dashes to
	278	# typographically correct entities.
7282a93f	279	html_use_smartypants = False
22cba31b JN	280
	281	# Custom sidebar templates, maps document names to template names.
	282	#html_sidebars = {}
	283
	284	# Additional templates that should be rendered to pages, maps page names to
	285	# template names.
	286	#html_additional_pages = {}
	287
	288	# If false, no module index is generated.
	289	#html_domain_indices = True
	290
	291	# If false, no index is generated.
	292	#html_use_index = True
	293
	294	# If true, the index is split into individual pages for each letter.
	295	#html_split_index = False
	296
	297	# If true, links to the reST sources are added to the pages.
	298	#html_show_sourcelink = True
	299
	300	# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
	301	#html_show_sphinx = True
	302
	303	# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
	304	#html_show_copyright = True
	305
	306	# If true, an OpenSearch description file will be output, and all pages will
	307	# contain a <link> tag referring to it. The value of this option must be the
	308	# base URL from which the finished HTML is served.
	309	#html_use_opensearch = ''
	310
	311	# This is the file name suffix for HTML files (e.g. ".xhtml").
	312	#html_file_suffix = None
	313
	314	# Language to be used for generating the HTML full-text search index.
	315	# Sphinx supports the following languages:
	316	# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
	317	# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
	318	#html_search_language = 'en'
	319
	320	# A dictionary with options for the search language support, empty by default.
	321	# Now only 'ja' uses this config value
	322	#html_search_options = {'type': 'default'}
	323
	324	# The name of a javascript file (relative to the configuration directory) that
	325	# implements a search results scorer. If empty, the default will be used.
	326	#html_search_scorer = 'scorer.js'
	327
	328	# Output file base name for HTML help builder.
	329	htmlhelp_basename = 'TheLinuxKerneldoc'
	330
	331	# -- Options for LaTeX output ---------------------------------------------
	332
	333	latex_elements = {
3b4c9632 MCC	334	# The paper size ('letterpaper' or 'a4paper').
3b4c9632 MCC	335	'papersize': 'a4paper',
22cba31b	336
3b4c9632 MCC	337	# The font size ('10pt', '11pt' or '12pt').
3b4c9632 MCC	338	'pointsize': '11pt',
22cba31b	339
3b4c9632 MCC	340	# Latex figure (float) alignment
3b4c9632 MCC	341	#'figure_align': 'htbp',
caee5cde	342
3b4c9632 MCC	343	# Don't mangle with UTF-8 chars
	344	'inputenc': '',
	345	'utf8extra': '',
a682ec4b	346
3b4c9632 MCC	347	# Set document margins
	348	'sphinxsetup': '''
	349	hmargin=0.5in, vmargin=1in,
	350	parsedliteralwraps=true,
	351	verbatimhintsturnover=false,
	352	''',
	353
	354	# Additional stuff for the LaTeX preamble.
caee5cde	355	'preamble': '''
3b4c9632	356	% Use some font with UTF-8 support with XeLaTeX
9fdcd6af	357	\\usepackage{fontspec}
44ba0bb4 DW	358	\\setsansfont{DejaVu Sans}
44ba0bb4 DW	359	\\setromanfont{DejaVu Serif}
9fdcd6af	360	\\setmonofont{DejaVu Sans Mono}
3b4c9632	361	''',
e0de2b59	362	}
9fdcd6af	363
e0de2b59 MCC	364	# At least one book (translations) may have Asian characters
	365	# with are only displayed if xeCJK is used
	366
	367	cjk_cmd = check_output(['fc-list', '--format="%{family[0]}\n"']).decode('utf-8', 'ignore')
	368	if cjk_cmd.find("Noto Sans CJK SC") >= 0:
	369	print ("enabling CJK for LaTeX builder")
	370	latex_elements['preamble'] += '''
24889dad MCC	371	% This is needed for translations
	372	\\usepackage{xeCJK}
	373	\\setCJKmainfont{Noto Sans CJK SC}
9fdcd6af	374	'''
9fdcd6af MCC	375
9fdcd6af MCC	376	# Fix reference escape troubles with Sphinx 1.4.x
f546ff0c	377	if major == 1:
9fdcd6af MCC	378	latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
9fdcd6af MCC	379
9fdcd6af MCC	380	# With Sphinx 1.6, it is possible to change the Bg color directly
	381	# by using:
	382	# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
	383	# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
	384	# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
	385	# \definecolor{sphinximportantBgColor}{RGB}{192,255,204}
	386	#
	387	# However, it require to use sphinx heavy box with:
	388	#
	389	# \renewenvironment{sphinxlightbox} {%
	390	# \\begin{sphinxheavybox}
	391	# }
	392	# \\end{sphinxheavybox}
	393	# }
	394	#
	395	# Unfortunately, the implementation is buggy: if a note is inside a
	396	# table, it isn't displayed well. So, for now, let's use boring
	397	# black and white notes.
633d612b	398
22cba31b JN	399	# Grouping the document tree into LaTeX files. List of tuples
	400	# (source start file, target name, title,
	401	# author, documentclass [howto, manual, or own class]).
c2b563d8	402	# Sorted in alphabetical order
22cba31b	403	latex_documents = [
22cba31b JN	404	]
22cba31b JN	405
9d42afbe MCC	406	# Add all other index files from Documentation/ subdirectories
	407	for fn in os.listdir('.'):
	408	doc = os.path.join(fn, "index")
	409	if os.path.exists(doc + ".rst"):
	410	has = False
	411	for l in latex_documents:
	412	if l[0] == doc:
	413	has = True
	414	break
	415	if not has:
	416	latex_documents.append((doc, fn + '.tex',
	417	'Linux %s Documentation' % fn.capitalize(),
	418	'The kernel development community',
	419	'manual'))
	420
22cba31b JN	421	# The name of an image file (relative to this directory) to place at the top of
	422	# the title page.
	423	#latex_logo = None
	424
	425	# For "manual" documents, if this is true, then toplevel headings are parts,
	426	# not chapters.
	427	#latex_use_parts = False
	428
	429	# If true, show page references after internal links.
	430	#latex_show_pagerefs = False
	431
	432	# If true, show URL addresses after external links.
	433	#latex_show_urls = False
	434
	435	# Documents to append as an appendix to all manuals.
	436	#latex_appendices = []
	437
	438	# If false, no module index is generated.
	439	#latex_domain_indices = True
	440
	441
	442	# -- Options for manual page output ---------------------------------------
	443
	444	# One entry per manual page. List of tuples
	445	# (source start file, name, description, authors, manual section).
	446	man_pages = [
	447	(master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
	448	[author], 1)
	449	]
	450
	451	# If true, show URL addresses after external links.
	452	#man_show_urls = False
	453
	454
	455	# -- Options for Texinfo output -------------------------------------------
	456
	457	# Grouping the document tree into Texinfo files. List of tuples
	458	# (source start file, target name, title, author,
	459	# dir menu entry, description, category)
	460	texinfo_documents = [
	461	(master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
	462	author, 'TheLinuxKernel', 'One line description of project.',
	463	'Miscellaneous'),
	464	]
	465
	466	# Documents to append as an appendix to all manuals.
	467	#texinfo_appendices = []
	468
	469	# If false, no module index is generated.
	470	#texinfo_domain_indices = True
	471
	472	# How to display URL addresses: 'footnote', 'no', or 'inline'.
	473	#texinfo_show_urls = 'footnote'
	474
	475	# If true, do not generate a @detailmenu in the "Top" node's menu.
	476	#texinfo_no_detailmenu = False
	477
	478
	479	# -- Options for Epub output ----------------------------------------------
	480
	481	# Bibliographic Dublin Core info.
	482	epub_title = project
	483	epub_author = author
	484	epub_publisher = author
485	epub_copyright = copyright
486
487	# The basename for the epub file. It defaults to the project name.
488	#epub_basename = project
489
490	# The HTML theme for the epub output. Since the default themes are not
491	# optimized for small screen space, using the same theme for HTML and epub
492	# output is usually not wise. This defaults to 'epub', a theme designed to save
493	# visual space.
494	#epub_theme = 'epub'
495
496	# The language of the text. It defaults to the language option
497	# or 'en' if the language is not set.
498	#epub_language = ''
499
500	# The scheme of the identifier. Typical schemes are ISBN or URL.
501	#epub_scheme = ''
502
503	# The unique identifier of the text. This can be a ISBN number
504	# or the project homepage.
505	#epub_identifier = ''
506
507	# A unique identification for the text.
508	#epub_uid = ''
509
510	# A tuple containing the cover image and cover page html template filenames.
511	#epub_cover = ()
512
513	# A sequence of (type, uri, title) tuples for the guide element of content.opf.
514	#epub_guide = ()
515
516	# HTML files that should be inserted before the pages created by sphinx.
517	# The format is a list of tuples containing the path and title.
518	#epub_pre_files = []
519
520	# HTML files that should be inserted after the pages created by sphinx.
521	# The format is a list of tuples containing the path and title.
522	#epub_post_files = []
523
524	# A list of files that should not be packed into the epub file.
525	epub_exclude_files = ['search.html']
526
527	# The depth of the table of contents in toc.ncx.
528	#epub_tocdepth = 3
529
530	# Allow duplicate toc entries.
531	#epub_tocdup = True
532
533	# Choose between 'default' and 'includehidden'.
534	#epub_tocscope = 'default'
535
536	# Fix unsupported image types using the Pillow.
537	#epub_fix_images = False
538
539	# Scale large images.
540	#epub_max_image_width = 0
541
542	# How to display URL addresses: 'footnote', 'no', or 'inline'.
543	#epub_show_urls = 'inline'
544
545	# If false, no index is generated.
546	#epub_use_index = True
547
548	#=======
549	# rst2pdf
550	#
551	# Grouping the document tree into PDF files. List of tuples
552	# (source start file, target name, title, author, options).
553	#
93431e06	554	# See the Sphinx chapter of https://ralsina.me/static/manual.pdf
22cba31b JN	555	#
	556	# FIXME: Do not add the index file here; the result will be too big. Adding
	557	# multiple PDF files here actually tries to get the cross-referencing right
	558	# between PDF files.
	559	pdf_documents = [
520a2477	560	('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
22cba31b	561	]
24dcdeb2 JN	562
	563	# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
	564	# the Docs). In a normal build, these are supplied from the Makefile via command
	565	# line arguments.
	566	kerneldoc_bin = '../scripts/kernel-doc'
	567	kerneldoc_srctree = '..'
606b9ac8 MH	568
	569	# ------------------------------------------------------------------------------
	570	# Since loadConfig overwrites settings from the global namespace, it has to be
	571	# the last statement in the conf.py file
	572	# ------------------------------------------------------------------------------
	573	loadConfig(globals())