About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / conf.py




Custom Search

Based on kernel version 4.9. Page generated on 2016-12-21 14:28 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 = map(int, sphinx.__version__.split("."))
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.0'
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 = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain']
38	
39	# The name of the math extension changed on Sphinx 1.4
40	if 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 = '2016, 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	        sys.stderr.write('Warning: Could not extract kernel version\n')
92	        version = release = "unknown version"
93	
94	# The language for content autogenerated by Sphinx. Refer to documentation
95	# for a list of supported languages.
96	#
97	# This is also used if you do content translation via gettext catalogs.
98	# Usually you set "language" from the command line for these cases.
99	language = None
100	
101	# There are two options for replacing |today|: either, you set today to some
102	# non-false value, then it is used:
103	#today = ''
104	# Else, today_fmt is used as the format for a strftime call.
105	#today_fmt = '%B %d, %Y'
106	
107	# List of patterns, relative to source directory, that match files and
108	# directories to ignore when looking for source files.
109	exclude_patterns = ['output']
110	
111	# The reST default role (used for this markup: `text`) to use for all
112	# documents.
113	#default_role = None
114	
115	# If true, '()' will be appended to :func: etc. cross-reference text.
116	#add_function_parentheses = True
117	
118	# If true, the current module name will be prepended to all description
119	# unit titles (such as .. function::).
120	#add_module_names = True
121	
122	# If true, sectionauthor and moduleauthor directives will be shown in the
123	# output. They are ignored by default.
124	#show_authors = False
125	
126	# The name of the Pygments (syntax highlighting) style to use.
127	pygments_style = 'sphinx'
128	
129	# A list of ignored prefixes for module index sorting.
130	#modindex_common_prefix = []
131	
132	# If true, keep warnings as "system message" paragraphs in the built documents.
133	#keep_warnings = False
134	
135	# If true, `todo` and `todoList` produce output, else they produce nothing.
136	todo_include_todos = False
137	
138	primary_domain = 'C'
139	highlight_language = 'guess'
140	
141	# -- Options for HTML output ----------------------------------------------
142	
143	# The theme to use for HTML and HTML Help pages.  See the documentation for
144	# a list of builtin themes.
145	
146	# The Read the Docs theme is available from
147	# - https://github.com/snide/sphinx_rtd_theme
148	# - https://pypi.python.org/pypi/sphinx_rtd_theme
149	# - python-sphinx-rtd-theme package (on Debian)
150	try:
151	    import sphinx_rtd_theme
152	    html_theme = 'sphinx_rtd_theme'
153	    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
154	except ImportError:
155	    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')
156	
157	# Theme options are theme-specific and customize the look and feel of a theme
158	# further.  For a list of options available for each theme, see the
159	# documentation.
160	#html_theme_options = {}
161	
162	# Add any paths that contain custom themes here, relative to this directory.
163	#html_theme_path = []
164	
165	# The name for this set of Sphinx documents.  If None, it defaults to
166	# "<project> v<release> documentation".
167	#html_title = None
168	
169	# A shorter title for the navigation bar.  Default is the same as html_title.
170	#html_short_title = None
171	
172	# The name of an image file (relative to this directory) to place at the top
173	# of the sidebar.
174	#html_logo = None
175	
176	# The name of an image file (within the static path) to use as favicon of the
177	# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
178	# pixels large.
179	#html_favicon = None
180	
181	# Add any paths that contain custom static files (such as style sheets) here,
182	# relative to this directory. They are copied after the builtin static files,
183	# so a file named "default.css" will overwrite the builtin "default.css".
184	
185	html_static_path = ['sphinx-static']
186	
187	html_context = {
188	    'css_files': [
189	        '_static/theme_overrides.css',
190	    ],
191	}
192	
193	# Add any extra paths that contain custom files (such as robots.txt or
194	# .htaccess) here, relative to this directory. These files are copied
195	# directly to the root of the documentation.
196	#html_extra_path = []
197	
198	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
199	# using the given strftime format.
200	#html_last_updated_fmt = '%b %d, %Y'
201	
202	# If true, SmartyPants will be used to convert quotes and dashes to
203	# typographically correct entities.
204	#html_use_smartypants = True
205	
206	# Custom sidebar templates, maps document names to template names.
207	#html_sidebars = {}
208	
209	# Additional templates that should be rendered to pages, maps page names to
210	# template names.
211	#html_additional_pages = {}
212	
213	# If false, no module index is generated.
214	#html_domain_indices = True
215	
216	# If false, no index is generated.
217	#html_use_index = True
218	
219	# If true, the index is split into individual pages for each letter.
220	#html_split_index = False
221	
222	# If true, links to the reST sources are added to the pages.
223	#html_show_sourcelink = True
224	
225	# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
226	#html_show_sphinx = True
227	
228	# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
229	#html_show_copyright = True
230	
231	# If true, an OpenSearch description file will be output, and all pages will
232	# contain a <link> tag referring to it.  The value of this option must be the
233	# base URL from which the finished HTML is served.
234	#html_use_opensearch = ''
235	
236	# This is the file name suffix for HTML files (e.g. ".xhtml").
237	#html_file_suffix = None
238	
239	# Language to be used for generating the HTML full-text search index.
240	# Sphinx supports the following languages:
241	#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
242	#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
243	#html_search_language = 'en'
244	
245	# A dictionary with options for the search language support, empty by default.
246	# Now only 'ja' uses this config value
247	#html_search_options = {'type': 'default'}
248	
249	# The name of a javascript file (relative to the configuration directory) that
250	# implements a search results scorer. If empty, the default will be used.
251	#html_search_scorer = 'scorer.js'
252	
253	# Output file base name for HTML help builder.
254	htmlhelp_basename = 'TheLinuxKerneldoc'
255	
256	# -- Options for LaTeX output ---------------------------------------------
257	
258	latex_elements = {
259	# The paper size ('letterpaper' or 'a4paper').
260	'papersize': 'a4paper',
261	
262	# The font size ('10pt', '11pt' or '12pt').
263	'pointsize': '8pt',
264	
265	# Latex figure (float) alignment
266	#'figure_align': 'htbp',
267	
268	# Don't mangle with UTF-8 chars
269	'inputenc': '',
270	'utf8extra': '',
271	
272	# Additional stuff for the LaTeX preamble.
273	    'preamble': '''
274		% Adjust margins
275		\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
276	
277	        % Allow generate some pages in landscape
278	        \\usepackage{lscape}
279	
280	        % Put notes in color and let them be inside a table
281		\\definecolor{NoteColor}{RGB}{204,255,255}
282		\\definecolor{WarningColor}{RGB}{255,204,204}
283		\\definecolor{AttentionColor}{RGB}{255,255,204}
284		\\definecolor{OtherColor}{RGB}{204,204,204}
285	        \\newlength{\\mynoticelength}
286	        \\makeatletter\\newenvironment{coloredbox}[1]{%
287		   \\setlength{\\fboxrule}{1pt}
288		   \\setlength{\\fboxsep}{7pt}
289		   \\setlength{\\mynoticelength}{\\linewidth}
290		   \\addtolength{\\mynoticelength}{-2\\fboxsep}
291		   \\addtolength{\\mynoticelength}{-2\\fboxrule}
292	           \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}%
293		   \\ifthenelse%
294		      {\\equal{\\py@noticetype}{note}}%
295		      {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}%
296		      {%
297		         \\ifthenelse%
298		         {\\equal{\\py@noticetype}{warning}}%
299		         {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}%
300			 {%
301		            \\ifthenelse%
302		            {\\equal{\\py@noticetype}{attention}}%
303		            {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}%
304		            {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}%
305			 }%
306		      }%
307	        }\\makeatother
308	
309	        \\makeatletter
310	        \\renewenvironment{notice}[2]{%
311	          \\def\\py@noticetype{#1}
312	          \\begin{coloredbox}{#1}
313	          \\bf\\it
314	          \\par\\strong{#2}
315	          \\csname py@noticestart@#1\\endcsname
316	        }
317		{
318	          \\csname py@noticeend@\\py@noticetype\\endcsname
319	          \\end{coloredbox}
320	        }
321		\\makeatother
322	
323		% Use some font with UTF-8 support with XeLaTeX
324	        \\usepackage{fontspec}
325	        \\setsansfont{DejaVu Serif}
326	        \\setromanfont{DejaVu Sans}
327	        \\setmonofont{DejaVu Sans Mono}
328	
329		% To allow adjusting table sizes
330		\\usepackage{adjustbox}
331	
332	     '''
333	}
334	
335	# Grouping the document tree into LaTeX files. List of tuples
336	# (source start file, target name, title,
337	#  author, documentclass [howto, manual, or own class]).
338	latex_documents = [
339	    ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
340	     'The kernel development community', 'manual'),
341	    ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
342	     'The kernel development community', 'manual'),
343	    ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
344	     'The kernel development community', 'manual'),
345	    ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
346	     'The kernel development community', 'manual'),
347	]
348	
349	# The name of an image file (relative to this directory) to place at the top of
350	# the title page.
351	#latex_logo = None
352	
353	# For "manual" documents, if this is true, then toplevel headings are parts,
354	# not chapters.
355	#latex_use_parts = False
356	
357	# If true, show page references after internal links.
358	#latex_show_pagerefs = False
359	
360	# If true, show URL addresses after external links.
361	#latex_show_urls = False
362	
363	# Documents to append as an appendix to all manuals.
364	#latex_appendices = []
365	
366	# If false, no module index is generated.
367	#latex_domain_indices = True
368	
369	
370	# -- Options for manual page output ---------------------------------------
371	
372	# One entry per manual page. List of tuples
373	# (source start file, name, description, authors, manual section).
374	man_pages = [
375	    (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
376	     [author], 1)
377	]
378	
379	# If true, show URL addresses after external links.
380	#man_show_urls = False
381	
382	
383	# -- Options for Texinfo output -------------------------------------------
384	
385	# Grouping the document tree into Texinfo files. List of tuples
386	# (source start file, target name, title, author,
387	#  dir menu entry, description, category)
388	texinfo_documents = [
389	    (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
390	     author, 'TheLinuxKernel', 'One line description of project.',
391	     'Miscellaneous'),
392	]
393	
394	# Documents to append as an appendix to all manuals.
395	#texinfo_appendices = []
396	
397	# If false, no module index is generated.
398	#texinfo_domain_indices = True
399	
400	# How to display URL addresses: 'footnote', 'no', or 'inline'.
401	#texinfo_show_urls = 'footnote'
402	
403	# If true, do not generate a @detailmenu in the "Top" node's menu.
404	#texinfo_no_detailmenu = False
405	
406	
407	# -- Options for Epub output ----------------------------------------------
408	
409	# Bibliographic Dublin Core info.
410	epub_title = project
411	epub_author = author
412	epub_publisher = author
413	epub_copyright = copyright
414	
415	# The basename for the epub file. It defaults to the project name.
416	#epub_basename = project
417	
418	# The HTML theme for the epub output. Since the default themes are not
419	# optimized for small screen space, using the same theme for HTML and epub
420	# output is usually not wise. This defaults to 'epub', a theme designed to save
421	# visual space.
422	#epub_theme = 'epub'
423	
424	# The language of the text. It defaults to the language option
425	# or 'en' if the language is not set.
426	#epub_language = ''
427	
428	# The scheme of the identifier. Typical schemes are ISBN or URL.
429	#epub_scheme = ''
430	
431	# The unique identifier of the text. This can be a ISBN number
432	# or the project homepage.
433	#epub_identifier = ''
434	
435	# A unique identification for the text.
436	#epub_uid = ''
437	
438	# A tuple containing the cover image and cover page html template filenames.
439	#epub_cover = ()
440	
441	# A sequence of (type, uri, title) tuples for the guide element of content.opf.
442	#epub_guide = ()
443	
444	# HTML files that should be inserted before the pages created by sphinx.
445	# The format is a list of tuples containing the path and title.
446	#epub_pre_files = []
447	
448	# HTML files that should be inserted after the pages created by sphinx.
449	# The format is a list of tuples containing the path and title.
450	#epub_post_files = []
451	
452	# A list of files that should not be packed into the epub file.
453	epub_exclude_files = ['search.html']
454	
455	# The depth of the table of contents in toc.ncx.
456	#epub_tocdepth = 3
457	
458	# Allow duplicate toc entries.
459	#epub_tocdup = True
460	
461	# Choose between 'default' and 'includehidden'.
462	#epub_tocscope = 'default'
463	
464	# Fix unsupported image types using the Pillow.
465	#epub_fix_images = False
466	
467	# Scale large images.
468	#epub_max_image_width = 0
469	
470	# How to display URL addresses: 'footnote', 'no', or 'inline'.
471	#epub_show_urls = 'inline'
472	
473	# If false, no index is generated.
474	#epub_use_index = True
475	
476	#=======
477	# rst2pdf
478	#
479	# Grouping the document tree into PDF files. List of tuples
480	# (source start file, target name, title, author, options).
481	#
482	# See the Sphinx chapter of http://ralsina.me/static/manual.pdf
483	#
484	# FIXME: Do not add the index file here; the result will be too big. Adding
485	# multiple PDF files here actually tries to get the cross-referencing right
486	# *between* PDF files.
487	pdf_documents = [
488	    ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
489	]
490	
491	# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
492	# the Docs). In a normal build, these are supplied from the Makefile via command
493	# line arguments.
494	kerneldoc_bin = '../scripts/kernel-doc'
495	kerneldoc_srctree = '..'
496	
497	# ------------------------------------------------------------------------------
498	# Since loadConfig overwrites settings from the global namespace, it has to be
499	# the last statement in the conf.py file
500	# ------------------------------------------------------------------------------
501	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.