About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / conf.py




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.