551 lines · python
1# -*- coding: utf-8 -*-2#3# The Linux Kernel documentation build configuration file, created by4# sphinx-quickstart on Fri Feb 12 13:51:46 2016.5#6# This file is execfile()d with the current directory set to its7# containing dir.8#9# Note that not all possible configuration values are present in this10# autogenerated file.11#12# All configuration values have a default; values that are commented out13# serve to show the default.14 15import sys16import os17import sphinx18import shutil19 20# helper21# ------22 23def 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 None30 31# Get Sphinx version32major, minor, patch = sphinx.version_info[:3]33 34#35# Warn about older versions that we don't want to support for much36# longer.37#38if (major < 2) or (major == 2 and minor < 4):39 print('WARNING: support for Sphinx < 2.4 will be removed soon.')40 41# If extensions (or modules to document with autodoc) are in another directory,42# add these directories to sys.path here. If the directory is relative to the43# documentation root, use os.path.abspath to make it absolute, like shown here.44sys.path.insert(0, os.path.abspath('sphinx'))45from load_config import loadConfig46 47# -- General configuration ------------------------------------------------48 49# If your documentation needs a minimal Sphinx version, state it here.50needs_sphinx = '2.4.4'51 52# Add any Sphinx extension module names here, as strings. They can be53# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom54# ones.55extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',56 'kfigure', 'sphinx.ext.ifconfig', 'automarkup',57 'maintainers_include', 'sphinx.ext.autosectionlabel',58 'kernel_abi', 'kernel_feat', 'translations']59 60if major >= 3:61 if (major > 3) or (minor > 0 or patch >= 2):62 # Sphinx c function parser is more pedantic with regards to type63 # checking. Due to that, having macros at c:function cause problems.64 # Those needed to be scaped by using c_id_attributes[] array65 c_id_attributes = [66 # GCC Compiler types not parsed by Sphinx:67 "__restrict__",68 69 # include/linux/compiler_types.h:70 "__iomem",71 "__kernel",72 "noinstr",73 "notrace",74 "__percpu",75 "__rcu",76 "__user",77 "__force",78 "__counted_by_le",79 "__counted_by_be",80 81 # include/linux/compiler_attributes.h:82 "__alias",83 "__aligned",84 "__aligned_largest",85 "__always_inline",86 "__assume_aligned",87 "__cold",88 "__attribute_const__",89 "__copy",90 "__pure",91 "__designated_init",92 "__visible",93 "__printf",94 "__scanf",95 "__gnu_inline",96 "__malloc",97 "__mode",98 "__no_caller_saved_registers",99 "__noclone",100 "__nonstring",101 "__noreturn",102 "__packed",103 "__pure",104 "__section",105 "__always_unused",106 "__maybe_unused",107 "__used",108 "__weak",109 "noinline",110 "__fix_address",111 "__counted_by",112 113 # include/linux/memblock.h:114 "__init_memblock",115 "__meminit",116 117 # include/linux/init.h:118 "__init",119 "__ref",120 121 # include/linux/linkage.h:122 "asmlinkage",123 124 # include/linux/btf.h125 "__bpf_kfunc",126 ]127 128else:129 extensions.append('cdomain')130 131# Ensure that autosectionlabel will produce unique names132autosectionlabel_prefix_document = True133autosectionlabel_maxdepth = 2134 135# Load math renderer:136# For html builder, load imgmath only when its dependencies are met.137# mathjax is the default math renderer since Sphinx 1.8.138have_latex = have_command('latex')139have_dvipng = have_command('dvipng')140load_imgmath = have_latex and have_dvipng141 142# Respect SPHINX_IMGMATH (for html docs only)143if 'SPHINX_IMGMATH' in os.environ:144 env_sphinx_imgmath = os.environ['SPHINX_IMGMATH']145 if 'yes' in env_sphinx_imgmath:146 load_imgmath = True147 elif 'no' in env_sphinx_imgmath:148 load_imgmath = False149 else:150 sys.stderr.write("Unknown env SPHINX_IMGMATH=%s ignored.\n" % env_sphinx_imgmath)151 152# Always load imgmath for Sphinx <1.8 or for epub docs153load_imgmath = (load_imgmath or (major == 1 and minor < 8)154 or 'epub' in sys.argv)155 156if load_imgmath:157 extensions.append("sphinx.ext.imgmath")158 math_renderer = 'imgmath'159else:160 math_renderer = 'mathjax'161 162# Add any paths that contain templates here, relative to this directory.163templates_path = ['sphinx/templates']164 165# The suffix(es) of source filenames.166# You can specify multiple suffix as a list of string:167# source_suffix = ['.rst', '.md']168source_suffix = '.rst'169 170# The encoding of source files.171#source_encoding = 'utf-8-sig'172 173# The master toctree document.174master_doc = 'index'175 176# General information about the project.177project = 'The Linux Kernel'178copyright = 'The kernel development community'179author = 'The kernel development community'180 181# The version info for the project you're documenting, acts as replacement for182# |version| and |release|, also used in various other places throughout the183# built documents.184#185# In a normal build, version and release are are set to KERNELVERSION and186# KERNELRELEASE, respectively, from the Makefile via Sphinx command line187# arguments.188#189# The following code tries to extract the information by reading the Makefile,190# when Sphinx is run directly (e.g. by Read the Docs).191try:192 makefile_version = None193 makefile_patchlevel = None194 for line in open('../Makefile'):195 key, val = [x.strip() for x in line.split('=', 2)]196 if key == 'VERSION':197 makefile_version = val198 elif key == 'PATCHLEVEL':199 makefile_patchlevel = val200 if makefile_version and makefile_patchlevel:201 break202except:203 pass204finally:205 if makefile_version and makefile_patchlevel:206 version = release = makefile_version + '.' + makefile_patchlevel207 else:208 version = release = "unknown version"209 210#211# HACK: there seems to be no easy way for us to get at the version and212# release information passed in from the makefile...so go pawing through the213# command-line options and find it for ourselves.214#215def get_cline_version():216 c_version = c_release = ''217 for arg in sys.argv:218 if arg.startswith('version='):219 c_version = arg[8:]220 elif arg.startswith('release='):221 c_release = arg[8:]222 if c_version:223 if c_release:224 return c_version + '-' + c_release225 return c_version226 return version # Whatever we came up with before227 228# The language for content autogenerated by Sphinx. Refer to documentation229# for a list of supported languages.230#231# This is also used if you do content translation via gettext catalogs.232# Usually you set "language" from the command line for these cases.233language = 'en'234 235# There are two options for replacing |today|: either, you set today to some236# non-false value, then it is used:237#today = ''238# Else, today_fmt is used as the format for a strftime call.239#today_fmt = '%B %d, %Y'240 241# List of patterns, relative to source directory, that match files and242# directories to ignore when looking for source files.243exclude_patterns = ['output']244 245# The reST default role (used for this markup: `text`) to use for all246# documents.247#default_role = None248 249# If true, '()' will be appended to :func: etc. cross-reference text.250#add_function_parentheses = True251 252# If true, the current module name will be prepended to all description253# unit titles (such as .. function::).254#add_module_names = True255 256# If true, sectionauthor and moduleauthor directives will be shown in the257# output. They are ignored by default.258#show_authors = False259 260# The name of the Pygments (syntax highlighting) style to use.261pygments_style = 'sphinx'262 263# A list of ignored prefixes for module index sorting.264#modindex_common_prefix = []265 266# If true, keep warnings as "system message" paragraphs in the built documents.267#keep_warnings = False268 269# If true, `todo` and `todoList` produce output, else they produce nothing.270todo_include_todos = False271 272primary_domain = 'c'273highlight_language = 'none'274 275# -- Options for HTML output ----------------------------------------------276 277# The theme to use for HTML and HTML Help pages. See the documentation for278# a list of builtin themes.279 280# Default theme281html_theme = 'alabaster'282html_css_files = []283 284if "DOCS_THEME" in os.environ:285 html_theme = os.environ["DOCS_THEME"]286 287if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':288 # Read the Docs theme289 try:290 import sphinx_rtd_theme291 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]292 293 # Add any paths that contain custom static files (such as style sheets) here,294 # relative to this directory. They are copied after the builtin static files,295 # so a file named "default.css" will overwrite the builtin "default.css".296 html_css_files = [297 'theme_overrides.css',298 ]299 300 # Read the Docs dark mode override theme301 if html_theme == 'sphinx_rtd_dark_mode':302 try:303 import sphinx_rtd_dark_mode304 extensions.append('sphinx_rtd_dark_mode')305 except ImportError:306 html_theme == 'sphinx_rtd_theme'307 308 if html_theme == 'sphinx_rtd_theme':309 # Add color-specific RTD normal mode310 html_css_files.append('theme_rtd_colors.css')311 312 html_theme_options = {313 'navigation_depth': -1,314 }315 316 except ImportError:317 html_theme = 'alabaster'318 319if "DOCS_CSS" in os.environ:320 css = os.environ["DOCS_CSS"].split(" ")321 322 for l in css:323 html_css_files.append(l)324 325if major <= 1 and minor < 8:326 html_context = {327 'css_files': [],328 }329 330 for l in html_css_files:331 html_context['css_files'].append('_static/' + l)332 333if html_theme == 'alabaster':334 html_theme_options = {335 'description': get_cline_version(),336 'page_width': '65em',337 'sidebar_width': '15em',338 'fixed_sidebar': 'true',339 'font_size': 'inherit',340 'font_family': 'serif',341 }342 343sys.stderr.write("Using %s theme\n" % html_theme)344 345# Add any paths that contain custom static files (such as style sheets) here,346# relative to this directory. They are copied after the builtin static files,347# so a file named "default.css" will overwrite the builtin "default.css".348html_static_path = ['sphinx-static']349 350# If true, Docutils "smart quotes" will be used to convert quotes and dashes351# to typographically correct entities. However, conversion of "--" to "—"352# is not always what we want, so enable only quotes.353smartquotes_action = 'q'354 355# Custom sidebar templates, maps document names to template names.356# Note that the RTD theme ignores this357html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']}358 359# about.html is available for alabaster theme. Add it at the front.360if html_theme == 'alabaster':361 html_sidebars['**'].insert(0, 'about.html')362 363# The name of an image file (relative to this directory) to place at the top364# of the sidebar.365html_logo = 'images/logo.svg'366 367# Output file base name for HTML help builder.368htmlhelp_basename = 'TheLinuxKerneldoc'369 370# -- Options for LaTeX output ---------------------------------------------371 372latex_elements = {373 # The paper size ('letterpaper' or 'a4paper').374 'papersize': 'a4paper',375 376 # The font size ('10pt', '11pt' or '12pt').377 'pointsize': '11pt',378 379 # Latex figure (float) alignment380 #'figure_align': 'htbp',381 382 # Don't mangle with UTF-8 chars383 'inputenc': '',384 'utf8extra': '',385 386 # Set document margins387 'sphinxsetup': '''388 hmargin=0.5in, vmargin=1in,389 parsedliteralwraps=true,390 verbatimhintsturnover=false,391 ''',392 393 #394 # Some of our authors are fond of deep nesting; tell latex to395 # cope.396 #397 'maxlistdepth': '10',398 399 # For CJK One-half spacing, need to be in front of hyperref400 'extrapackages': r'\usepackage{setspace}',401 402 # Additional stuff for the LaTeX preamble.403 'preamble': '''404 % Use some font with UTF-8 support with XeLaTeX405 \\usepackage{fontspec}406 \\setsansfont{DejaVu Sans}407 \\setromanfont{DejaVu Serif}408 \\setmonofont{DejaVu Sans Mono}409 ''',410}411 412# Fix reference escape troubles with Sphinx 1.4.x413if major == 1:414 latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'415 416 417# Load kerneldoc specific LaTeX settings418latex_elements['preamble'] += '''419 % Load kerneldoc specific LaTeX settings420 \\input{kerneldoc-preamble.sty}421'''422 423# With Sphinx 1.6, it is possible to change the Bg color directly424# by using:425# \definecolor{sphinxnoteBgColor}{RGB}{204,255,255}426# \definecolor{sphinxwarningBgColor}{RGB}{255,204,204}427# \definecolor{sphinxattentionBgColor}{RGB}{255,255,204}428# \definecolor{sphinximportantBgColor}{RGB}{192,255,204}429#430# However, it require to use sphinx heavy box with:431#432# \renewenvironment{sphinxlightbox} {%433# \\begin{sphinxheavybox}434# }435# \\end{sphinxheavybox}436# }437#438# Unfortunately, the implementation is buggy: if a note is inside a439# table, it isn't displayed well. So, for now, let's use boring440# black and white notes.441 442# Grouping the document tree into LaTeX files. List of tuples443# (source start file, target name, title,444# author, documentclass [howto, manual, or own class]).445# Sorted in alphabetical order446latex_documents = [447]448 449# Add all other index files from Documentation/ subdirectories450for fn in os.listdir('.'):451 doc = os.path.join(fn, "index")452 if os.path.exists(doc + ".rst"):453 has = False454 for l in latex_documents:455 if l[0] == doc:456 has = True457 break458 if not has:459 latex_documents.append((doc, fn + '.tex',460 'Linux %s Documentation' % fn.capitalize(),461 'The kernel development community',462 'manual'))463 464# The name of an image file (relative to this directory) to place at the top of465# the title page.466#latex_logo = None467 468# For "manual" documents, if this is true, then toplevel headings are parts,469# not chapters.470#latex_use_parts = False471 472# If true, show page references after internal links.473#latex_show_pagerefs = False474 475# If true, show URL addresses after external links.476#latex_show_urls = False477 478# Documents to append as an appendix to all manuals.479#latex_appendices = []480 481# If false, no module index is generated.482#latex_domain_indices = True483 484# Additional LaTeX stuff to be copied to build directory485latex_additional_files = [486 'sphinx/kerneldoc-preamble.sty',487]488 489 490# -- Options for manual page output ---------------------------------------491 492# One entry per manual page. List of tuples493# (source start file, name, description, authors, manual section).494man_pages = [495 (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',496 [author], 1)497]498 499# If true, show URL addresses after external links.500#man_show_urls = False501 502 503# -- Options for Texinfo output -------------------------------------------504 505# Grouping the document tree into Texinfo files. List of tuples506# (source start file, target name, title, author,507# dir menu entry, description, category)508texinfo_documents = [509 (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',510 author, 'TheLinuxKernel', 'One line description of project.',511 'Miscellaneous'),512]513 514# -- Options for Epub output ----------------------------------------------515 516# Bibliographic Dublin Core info.517epub_title = project518epub_author = author519epub_publisher = author520epub_copyright = copyright521 522# A list of files that should not be packed into the epub file.523epub_exclude_files = ['search.html']524 525#=======526# rst2pdf527#528# Grouping the document tree into PDF files. List of tuples529# (source start file, target name, title, author, options).530#531# See the Sphinx chapter of https://ralsina.me/static/manual.pdf532#533# FIXME: Do not add the index file here; the result will be too big. Adding534# multiple PDF files here actually tries to get the cross-referencing right535# *between* PDF files.536pdf_documents = [537 ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),538]539 540# kernel-doc extension configuration for running Sphinx directly (e.g. by Read541# the Docs). In a normal build, these are supplied from the Makefile via command542# line arguments.543kerneldoc_bin = '../scripts/kernel-doc'544kerneldoc_srctree = '..'545 546# ------------------------------------------------------------------------------547# Since loadConfig overwrites settings from the global namespace, it has to be548# the last statement in the conf.py file549# ------------------------------------------------------------------------------550loadConfig(globals())551