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