[linux-block.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
import shutil

# helper
# ------

def have_command(cmd):
    """Search ``cmd`` in the ``PATH`` environment.

    If found, return True.
    If not found, return False.
    """
    return shutil.which(cmd) is not None

# 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 = '3.4.3'

# 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', 'translations']

# Since Sphinx version 3, the 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
c_id_attributes = [
    # GCC Compiler types not parsed by Sphinx:
    "__restrict__",

    # include/linux/compiler_types.h:
    "__iomem",
    "__kernel",
    "noinstr",
    "notrace",
    "__percpu",
    "__rcu",
    "__user",
    "__force",
    "__counted_by_le",
    "__counted_by_be",

    # 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",
    "__fix_address",
    "__counted_by",

    # include/linux/memblock.h:
    "__init_memblock",
    "__meminit",

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

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

    # include/linux/btf.h
    "__bpf_kfunc",
]

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

# Load math renderer:
# For html builder, load imgmath only when its dependencies are met.
# mathjax is the default math renderer since Sphinx 1.8.
have_latex =  have_command('latex')
have_dvipng = have_command('dvipng')
load_imgmath = have_latex and have_dvipng

# Respect SPHINX_IMGMATH (for html docs only)
if 'SPHINX_IMGMATH' in os.environ:
    env_sphinx_imgmath = os.environ['SPHINX_IMGMATH']
    if 'yes' in env_sphinx_imgmath:
        load_imgmath = True
    elif 'no' in env_sphinx_imgmath:
        load_imgmath = False
    else:
        sys.stderr.write("Unknown env SPHINX_IMGMATH=%s ignored.\n" % env_sphinx_imgmath)

if load_imgmath:
    extensions.append("sphinx.ext.imgmath")
    math_renderer = 'imgmath'
else:
    math_renderer = 'mathjax'

# Add any paths that contain templates here, relative to this directory.
templates_path = ['sphinx/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"

#
# HACK: there seems to be no easy way for us to get at the version and
# release information passed in from the makefile...so go pawing through the
# command-line options and find it for ourselves.
#
def get_cline_version():
    c_version = c_release = ''
    for arg in sys.argv:
        if arg.startswith('version='):
            c_version = arg[8:]
        elif arg.startswith('release='):
            c_release = arg[8:]
    if c_version:
        if c_release:
            return c_version + '-' + c_release
        return c_version
    return version # Whatever we came up with before

# 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 = 'en'

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

# Default theme
html_theme = 'alabaster'
html_css_files = []

if "DOCS_THEME" in os.environ:
    html_theme = os.environ["DOCS_THEME"]

if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
    # Read the Docs theme
    try:
        import sphinx_rtd_theme
        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

        # 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_css_files = [
            'theme_overrides.css',
        ]

        # Read the Docs dark mode override theme
        if html_theme == 'sphinx_rtd_dark_mode':
            try:
                import sphinx_rtd_dark_mode
                extensions.append('sphinx_rtd_dark_mode')
            except ImportError:
                html_theme == 'sphinx_rtd_theme'

        if html_theme == 'sphinx_rtd_theme':
                # Add color-specific RTD normal mode
                html_css_files.append('theme_rtd_colors.css')

        html_theme_options = {
            'navigation_depth': -1,
        }

    except ImportError:
        html_theme = 'alabaster'

if "DOCS_CSS" in os.environ:
    css = os.environ["DOCS_CSS"].split(" ")

    for l in css:
        html_css_files.append(l)

if  html_theme == 'alabaster':
    html_theme_options = {
        'description': get_cline_version(),
        'page_width': '65em',
        'sidebar_width': '15em',
        'fixed_sidebar': 'true',
        'font_size': 'inherit',
        'font_family': 'serif',
    }

sys.stderr.write("Using %s theme\n" % html_theme)

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

# If true, Docutils "smart quotes" will be used to convert quotes and dashes
# to typographically correct entities.  However, conversion of "--" to "—"
# is not always what we want, so enable only quotes.
smartquotes_action = 'q'

# Custom sidebar templates, maps document names to template names.
# Note that the RTD theme ignores this
html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']}

# about.html is available for alabaster theme. Add it at the front.
if html_theme == 'alabaster':
    html_sidebars['**'].insert(0, 'about.html')

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = 'images/logo.svg'

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

    #
    # Some of our authors are fond of deep nesting; tell latex to
    # cope.
    #
    'maxlistdepth': '10',

    # For CJK One-half spacing, need to be in front of hyperref
    'extrapackages': r'\usepackage{setspace}',

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

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

# Additional LaTeX stuff to be copied to build directory
latex_additional_files = [
    'sphinx/kerneldoc-preamble.sty',
]


# -- 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'),
]

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

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

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

#=======
# 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.py'
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	17	import sphinx
6b0d3e7c AY	18	import shutil
	19
	20	# helper
	21	# ------
	22
	23	def have_command(cmd):
	24	"""Search ``cmd`` in the ``PATH`` environment.
	25
	26	If found, return True.
	27	If not found, return False.
	28	"""
	29	return shutil.which(cmd) is not None
d4fe7e14	30
22cba31b JN	31	# If extensions (or modules to document with autodoc) are in another directory,
	32	# add these directories to sys.path here. If the directory is relative to the
	33	# documentation root, use os.path.abspath to make it absolute, like shown here.
24dcdeb2	34	sys.path.insert(0, os.path.abspath('sphinx'))
606b9ac8	35	from load_config import loadConfig
22cba31b JN	36
	37	# -- General configuration ------------------------------------------------
	38
	39	# If your documentation needs a minimal Sphinx version, state it here.
d2b23909	40	needs_sphinx = '3.4.3'
22cba31b JN	41
	42	# Add any Sphinx extension module names here, as strings. They can be
	43	# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
	44	# ones.
afde706a	45	extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
aa204855	46	'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
a7ee04b3	47	'maintainers_include', 'sphinx.ext.autosectionlabel',
7418ec5b	48	'kernel_abi', 'kernel_feat', 'translations']
22cba31b	49
b2671785 MCC	50	# Since Sphinx version 3, the C function parser is more pedantic with regards
	51	# to type checking. Due to that, having macros at c:function cause problems.
	52	# Those needed to be escaped by using c_id_attributes[] array
	53	c_id_attributes = [
	54	# GCC Compiler types not parsed by Sphinx:
	55	"__restrict__",
	56
	57	# include/linux/compiler_types.h:
	58	"__iomem",
	59	"__kernel",
	60	"noinstr",
	61	"notrace",
	62	"__percpu",
	63	"__rcu",
	64	"__user",
	65	"__force",
	66	"__counted_by_le",
	67	"__counted_by_be",
	68
	69	# include/linux/compiler_attributes.h:
	70	"__alias",
	71	"__aligned",
	72	"__aligned_largest",
	73	"__always_inline",
	74	"__assume_aligned",
	75	"__cold",
	76	"__attribute_const__",
	77	"__copy",
	78	"__pure",
	79	"__designated_init",
	80	"__visible",
	81	"__printf",
	82	"__scanf",
	83	"__gnu_inline",
	84	"__malloc",
	85	"__mode",
	86	"__no_caller_saved_registers",
	87	"__noclone",
	88	"__nonstring",
	89	"__noreturn",
	90	"__packed",
	91	"__pure",
	92	"__section",
	93	"__always_unused",
	94	"__maybe_unused",
	95	"__used",
	96	"__weak",
	97	"noinline",
	98	"__fix_address",
	99	"__counted_by",
	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	# include/linux/btf.h
	113	"__bpf_kfunc",
114	]
afde706a	115
4658b0eb MCC	116	# Ensure that autosectionlabel will produce unique names
	117	autosectionlabel_prefix_document = True
	118	autosectionlabel_maxdepth = 2
	119
6b0d3e7c AY	120	# Load math renderer:
	121	# For html builder, load imgmath only when its dependencies are met.
	122	# mathjax is the default math renderer since Sphinx 1.8.
	123	have_latex = have_command('latex')
	124	have_dvipng = have_command('dvipng')
3b384e95 AY	125	load_imgmath = have_latex and have_dvipng
	126
	127	# Respect SPHINX_IMGMATH (for html docs only)
	128	if 'SPHINX_IMGMATH' in os.environ:
	129	env_sphinx_imgmath = os.environ['SPHINX_IMGMATH']
	130	if 'yes' in env_sphinx_imgmath:
	131	load_imgmath = True
	132	elif 'no' in env_sphinx_imgmath:
	133	load_imgmath = False
	134	else:
	135	sys.stderr.write("Unknown env SPHINX_IMGMATH=%s ignored.\n" % env_sphinx_imgmath)
	136
6b0d3e7c AY	137	if load_imgmath:
	138	extensions.append("sphinx.ext.imgmath")
	139	math_renderer = 'imgmath'
	140	else:
	141	math_renderer = 'mathjax'
22cba31b JN	142
22cba31b JN	143	# Add any paths that contain templates here, relative to this directory.
c404f5d4	144	templates_path = ['sphinx/templates']
22cba31b JN	145
	146	# The suffix(es) of source filenames.
	147	# You can specify multiple suffix as a list of string:
	148	# source_suffix = ['.rst', '.md']
	149	source_suffix = '.rst'
	150
	151	# The encoding of source files.
	152	#source_encoding = 'utf-8-sig'
	153
	154	# The master toctree document.
	155	master_doc = 'index'
	156
	157	# General information about the project.
	158	project = 'The Linux Kernel'
dc36143f	159	copyright = 'The kernel development community'
22cba31b JN	160	author = 'The kernel development community'
	161
	162	# The version info for the project you're documenting, acts as replacement for
	163	# \|version\| and \|release\|, also used in various other places throughout the
	164	# built documents.
	165	#
c13ce448 JN	166	# In a normal build, version and release are are set to KERNELVERSION and
	167	# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
	168	# arguments.
	169	#
	170	# The following code tries to extract the information by reading the Makefile,
	171	# when Sphinx is run directly (e.g. by Read the Docs).
	172	try:
	173	makefile_version = None
	174	makefile_patchlevel = None
	175	for line in open('../Makefile'):
	176	key, val = [x.strip() for x in line.split('=', 2)]
	177	if key == 'VERSION':
	178	makefile_version = val
	179	elif key == 'PATCHLEVEL':
	180	makefile_patchlevel = val
	181	if makefile_version and makefile_patchlevel:
	182	break
	183	except:
	184	pass
	185	finally:
	186	if makefile_version and makefile_patchlevel:
	187	version = release = makefile_version + '.' + makefile_patchlevel
	188	else:
c13ce448	189	version = release = "unknown version"
22cba31b	190
d5389d31 JC	191	#
	192	# HACK: there seems to be no easy way for us to get at the version and
	193	# release information passed in from the makefile...so go pawing through the
	194	# command-line options and find it for ourselves.
	195	#
	196	def get_cline_version():
	197	c_version = c_release = ''
	198	for arg in sys.argv:
	199	if arg.startswith('version='):
	200	c_version = arg[8:]
	201	elif arg.startswith('release='):
	202	c_release = arg[8:]
	203	if c_version:
	204	if c_release:
	205	return c_version + '-' + c_release
	206	return c_version
	207	return version # Whatever we came up with before
	208
22cba31b JN	209	# The language for content autogenerated by Sphinx. Refer to documentation
	210	# for a list of supported languages.
	211	#
	212	# This is also used if you do content translation via gettext catalogs.
	213	# Usually you set "language" from the command line for these cases.
627f01ea	214	language = 'en'
22cba31b JN	215
	216	# There are two options for replacing \|today\|: either, you set today to some
	217	# non-false value, then it is used:
	218	#today = ''
	219	# Else, today_fmt is used as the format for a strftime call.
	220	#today_fmt = '%B %d, %Y'
	221
	222	# List of patterns, relative to source directory, that match files and
	223	# directories to ignore when looking for source files.
	224	exclude_patterns = ['output']
	225
	226	# The reST default role (used for this markup: `text`) to use for all
	227	# documents.
	228	#default_role = None
	229
	230	# If true, '()' will be appended to :func: etc. cross-reference text.
	231	#add_function_parentheses = True
	232
	233	# If true, the current module name will be prepended to all description
	234	# unit titles (such as .. function::).
	235	#add_module_names = True
	236
	237	# If true, sectionauthor and moduleauthor directives will be shown in the
	238	# output. They are ignored by default.
	239	#show_authors = False
	240
	241	# The name of the Pygments (syntax highlighting) style to use.
	242	pygments_style = 'sphinx'
	243
	244	# A list of ignored prefixes for module index sorting.
	245	#modindex_common_prefix = []
	246
	247	# If true, keep warnings as "system message" paragraphs in the built documents.
	248	#keep_warnings = False
	249
	250	# If true, `todo` and `todoList` produce output, else they produce nothing.
	251	todo_include_todos = False
	252
fd5d6669	253	primary_domain = 'c'
b459106e	254	highlight_language = 'none'
22cba31b JN	255
	256	# -- Options for HTML output ----------------------------------------------
	257
	258	# The theme to use for HTML and HTML Help pages. See the documentation for
	259	# a list of builtin themes.
	260
fca7216b	261	# Default theme
d5389d31	262	html_theme = 'alabaster'
135707d3	263	html_css_files = []
fca7216b MCC	264
	265	if "DOCS_THEME" in os.environ:
	266	html_theme = os.environ["DOCS_THEME"]
	267
a6fb8b5a	268	if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
fca7216b MCC	269	# Read the Docs theme
	270	try:
	271	import sphinx_rtd_theme
	272	html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
	273
	274	# Add any paths that contain custom static files (such as style sheets) here,
	275	# relative to this directory. They are copied after the builtin static files,
	276	# so a file named "default.css" will overwrite the builtin "default.css".
	277	html_css_files = [
	278	'theme_overrides.css',
	279	]
a6fb8b5a MCC	280
	281	# Read the Docs dark mode override theme
	282	if html_theme == 'sphinx_rtd_dark_mode':
	283	try:
	284	import sphinx_rtd_dark_mode
	285	extensions.append('sphinx_rtd_dark_mode')
	286	except ImportError:
	287	html_theme == 'sphinx_rtd_theme'
	288
	289	if html_theme == 'sphinx_rtd_theme':
	290	# Add color-specific RTD normal mode
	291	html_css_files.append('theme_rtd_colors.css')
	292
e17f2260 DV	293	html_theme_options = {
	294	'navigation_depth': -1,
	295	}
	296
fca7216b	297	except ImportError:
02d33e86	298	html_theme = 'alabaster'
fca7216b	299
135707d3 MCC	300	if "DOCS_CSS" in os.environ:
	301	css = os.environ["DOCS_CSS"].split(" ")
	302
	303	for l in css:
	304	html_css_files.append(l)
	305
02d33e86	306	if html_theme == 'alabaster':
d5389d31 JC	307	html_theme_options = {
d5389d31 JC	308	'description': get_cline_version(),
2056b920 JC	309	'page_width': '65em',
2056b920 JC	310	'sidebar_width': '15em',
c404f5d4	311	'fixed_sidebar': 'true',
bd5d1cc8 JC	312	'font_size': 'inherit',
bd5d1cc8 JC	313	'font_family': 'serif',
d5389d31	314	}
ffc901b4	315
fca7216b	316	sys.stderr.write("Using %s theme\n" % html_theme)
22cba31b	317
22cba31b JN	318	# Add any paths that contain custom static files (such as style sheets) here,
	319	# relative to this directory. They are copied after the builtin static files,
	320	# so a file named "default.css" will overwrite the builtin "default.css".
bc214671 MH	321	html_static_path = ['sphinx-static']
bc214671 MH	322
eaae7575	323	# If true, Docutils "smart quotes" will be used to convert quotes and dashes
fe256258 AY	324	# to typographically correct entities. However, conversion of "--" to "—"
	325	# is not always what we want, so enable only quotes.
	326	smartquotes_action = 'q'
22cba31b JN	327
22cba31b JN	328	# Custom sidebar templates, maps document names to template names.
d5389d31	329	# Note that the RTD theme ignores this
c404f5d4	330	html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']}
a33ae832 AY	331
	332	# about.html is available for alabaster theme. Add it at the front.
	333	if html_theme == 'alabaster':
	334	html_sidebars['**'].insert(0, 'about.html')
22cba31b	335
d49af114 VN	336	# The name of an image file (relative to this directory) to place at the top
	337	# of the sidebar.
	338	html_logo = 'images/logo.svg'
	339
22cba31b JN	340	# Output file base name for HTML help builder.
	341	htmlhelp_basename = 'TheLinuxKerneldoc'
	342
	343	# -- Options for LaTeX output ---------------------------------------------
	344
	345	latex_elements = {
3b4c9632 MCC	346	# The paper size ('letterpaper' or 'a4paper').
3b4c9632 MCC	347	'papersize': 'a4paper',
22cba31b	348
3b4c9632 MCC	349	# The font size ('10pt', '11pt' or '12pt').
3b4c9632 MCC	350	'pointsize': '11pt',
22cba31b	351
3b4c9632 MCC	352	# Latex figure (float) alignment
3b4c9632 MCC	353	#'figure_align': 'htbp',
caee5cde	354
3b4c9632 MCC	355	# Don't mangle with UTF-8 chars
	356	'inputenc': '',
	357	'utf8extra': '',
a682ec4b	358
3b4c9632 MCC	359	# Set document margins
	360	'sphinxsetup': '''
	361	hmargin=0.5in, vmargin=1in,
	362	parsedliteralwraps=true,
	363	verbatimhintsturnover=false,
	364	''',
	365
0df8669f JC	366	#
	367	# Some of our authors are fond of deep nesting; tell latex to
	368	# cope.
	369	#
	370	'maxlistdepth': '10',
	371
77abc2c2 AY	372	# For CJK One-half spacing, need to be in front of hyperref
	373	'extrapackages': r'\usepackage{setspace}',
	374
3b4c9632	375	# Additional stuff for the LaTeX preamble.
caee5cde	376	'preamble': '''
3b4c9632	377	% Use some font with UTF-8 support with XeLaTeX
9fdcd6af	378	\\usepackage{fontspec}
44ba0bb4 DW	379	\\setsansfont{DejaVu Sans}
44ba0bb4 DW	380	\\setromanfont{DejaVu Serif}
9fdcd6af	381	\\setmonofont{DejaVu Sans Mono}
398f7abd	382	''',
e0de2b59	383	}
9fdcd6af	384
398f7abd AY	385	# Load kerneldoc specific LaTeX settings
	386	latex_elements['preamble'] += '''
	387	% Load kerneldoc specific LaTeX settings
	388	\\input{kerneldoc-preamble.sty}
	389	'''
	390
9fdcd6af MCC	391	# With Sphinx 1.6, it is possible to change the Bg color directly
	392	# by using:
	393	# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}
	394	# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204}
	395	# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204}
	396	# \definecolor{sphinximportantBgColor}{RGB}{192,255,204}
	397	#
	398	# However, it require to use sphinx heavy box with:
	399	#
	400	# \renewenvironment{sphinxlightbox} {%
	401	# \\begin{sphinxheavybox}
	402	# }
	403	# \\end{sphinxheavybox}
	404	# }
	405	#
	406	# Unfortunately, the implementation is buggy: if a note is inside a
	407	# table, it isn't displayed well. So, for now, let's use boring
	408	# black and white notes.
633d612b	409
22cba31b JN	410	# Grouping the document tree into LaTeX files. List of tuples
	411	# (source start file, target name, title,
	412	# author, documentclass [howto, manual, or own class]).
c2b563d8	413	# Sorted in alphabetical order
22cba31b	414	latex_documents = [
22cba31b JN	415	]
22cba31b JN	416
9d42afbe MCC	417	# Add all other index files from Documentation/ subdirectories
	418	for fn in os.listdir('.'):
	419	doc = os.path.join(fn, "index")
	420	if os.path.exists(doc + ".rst"):
	421	has = False
	422	for l in latex_documents:
	423	if l[0] == doc:
	424	has = True
	425	break
	426	if not has:
	427	latex_documents.append((doc, fn + '.tex',
	428	'Linux %s Documentation' % fn.capitalize(),
	429	'The kernel development community',
	430	'manual'))
	431
22cba31b JN	432	# The name of an image file (relative to this directory) to place at the top of
	433	# the title page.
	434	#latex_logo = None
	435
	436	# For "manual" documents, if this is true, then toplevel headings are parts,
	437	# not chapters.
	438	#latex_use_parts = False
	439
	440	# If true, show page references after internal links.
	441	#latex_show_pagerefs = False
	442
	443	# If true, show URL addresses after external links.
	444	#latex_show_urls = False
	445
	446	# Documents to append as an appendix to all manuals.
	447	#latex_appendices = []
	448
	449	# If false, no module index is generated.
	450	#latex_domain_indices = True
	451
398f7abd AY	452	# Additional LaTeX stuff to be copied to build directory
	453	latex_additional_files = [
	454	'sphinx/kerneldoc-preamble.sty',
	455	]
	456
22cba31b JN	457
	458	# -- Options for manual page output ---------------------------------------
	459
	460	# One entry per manual page. List of tuples
	461	# (source start file, name, description, authors, manual section).
	462	man_pages = [
	463	(master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
	464	[author], 1)
	465	]
	466
	467	# If true, show URL addresses after external links.
	468	#man_show_urls = False
	469
	470
	471	# -- Options for Texinfo output -------------------------------------------
	472
	473	# Grouping the document tree into Texinfo files. List of tuples
	474	# (source start file, target name, title, author,
	475	# dir menu entry, description, category)
	476	texinfo_documents = [
	477	(master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
	478	author, 'TheLinuxKernel', 'One line description of project.',
	479	'Miscellaneous'),
	480	]
	481
22cba31b JN	482	# -- Options for Epub output ----------------------------------------------
	483
	484	# Bibliographic Dublin Core info.
	485	epub_title = project
	486	epub_author = author
	487	epub_publisher = author
	488	epub_copyright = copyright
	489
22cba31b JN	490	# A list of files that should not be packed into the epub file.
	491	epub_exclude_files = ['search.html']
	492
22cba31b JN	493	#=======
	494	# rst2pdf
	495	#
	496	# Grouping the document tree into PDF files. List of tuples
	497	# (source start file, target name, title, author, options).
	498	#
93431e06	499	# See the Sphinx chapter of https://ralsina.me/static/manual.pdf
22cba31b JN	500	#
	501	# FIXME: Do not add the index file here; the result will be too big. Adding
	502	# multiple PDF files here actually tries to get the cross-referencing right
	503	# between PDF files.
	504	pdf_documents = [
520a2477	505	('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
22cba31b	506	]
24dcdeb2 JN	507
	508	# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
	509	# the Docs). In a normal build, these are supplied from the Makefile via command
	510	# line arguments.
feec6107	511	kerneldoc_bin = '../scripts/kernel-doc.py'
24dcdeb2	512	kerneldoc_srctree = '..'
606b9ac8 MH	513
	514	# ------------------------------------------------------------------------------
	515	# Since loadConfig overwrites settings from the global namespace, it has to be
	516	# the last statement in the conf.py file
	517	# ------------------------------------------------------------------------------
	518	loadConfig(globals())