1# -*- coding: utf-8 -*- 2# 3# QEMU documentation build configuration file, created by 4# sphinx-quickstart on Thu Jan 31 16:40:14 2019. 5# 6# This config file can be used in one of two ways: 7# (1) as a common config file which is included by the conf.py 8# for each of QEMU's manuals: in this case sphinx-build is run multiple 9# times, once per subdirectory. 10# (2) as a top level conf file which will result in building all 11# the manuals into a single document: in this case sphinx-build is 12# run once, on the top-level docs directory. 13# 14# QEMU's makefiles take option (1), which allows us to install 15# only the ones the user cares about (in particular we don't want 16# to ship the 'devel' manual to end-users). 17# Third-party sites such as readthedocs.org will take option (2). 18# 19# 20# This file is execfile()d with the current directory set to its 21# containing dir. 22# 23# Note that not all possible configuration values are present in this 24# autogenerated file. 25# 26# All configuration values have a default; values that are commented out 27# serve to show the default. 28 29import os 30import sys 31 32# The per-manual conf.py will set qemu_docdir for a single-manual build; 33# otherwise set it here if this is an entire-manual-set build. 34# This is always the absolute path of the docs/ directory in the source tree. 35try: 36 qemu_docdir 37except NameError: 38 qemu_docdir = os.path.abspath(".") 39 40# If extensions (or modules to document with autodoc) are in another directory, 41# add these directories to sys.path here. If the directory is relative to the 42# documentation root, use an absolute path starting from qemu_docdir. 43# 44sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) 45 46 47# -- General configuration ------------------------------------------------ 48 49# If your documentation needs a minimal Sphinx version, state it here. 50# 51# 1.3 is where the 'alabaster' theme was shipped with Sphinx. 52needs_sphinx = '1.3' 53 54# Add any Sphinx extension module names here, as strings. They can be 55# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 56# ones. 57extensions = ['kerneldoc', 'qmp_lexer', 'hxtool'] 58 59# Add any paths that contain templates here, relative to this directory. 60templates_path = ['_templates'] 61 62# The suffix(es) of source filenames. 63# You can specify multiple suffix as a list of string: 64# 65# source_suffix = ['.rst', '.md'] 66source_suffix = '.rst' 67 68# The master toctree document. 69master_doc = 'index' 70 71# General information about the project. 72project = u'QEMU' 73copyright = u'2019, The QEMU Project Developers' 74author = u'The QEMU Project Developers' 75 76# The version info for the project you're documenting, acts as replacement for 77# |version| and |release|, also used in various other places throughout the 78# built documents. 79 80# Extract this information from the VERSION file, for the benefit of 81# standalone Sphinx runs as used by readthedocs.org. Builds run from 82# the Makefile will pass version and release on the sphinx-build 83# command line, which override this. 84try: 85 extracted_version = None 86 with open(os.path.join(qemu_docdir, '../VERSION')) as f: 87 extracted_version = f.readline().strip() 88except: 89 pass 90finally: 91 if extracted_version: 92 version = release = extracted_version 93 else: 94 version = release = "unknown version" 95 96# The language for content autogenerated by Sphinx. Refer to documentation 97# for a list of supported languages. 98# 99# This is also used if you do content translation via gettext catalogs. 100# Usually you set "language" from the command line for these cases. 101language = None 102 103# List of patterns, relative to source directory, that match files and 104# directories to ignore when looking for source files. 105# This patterns also effect to html_static_path and html_extra_path 106exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 107 108# The name of the Pygments (syntax highlighting) style to use. 109pygments_style = 'sphinx' 110 111# If true, `todo` and `todoList` produce output, else they produce nothing. 112todo_include_todos = False 113 114# Sphinx defaults to warning about use of :option: for options not defined 115# with "option::" in the document being processed. Turn that off. 116suppress_warnings = ["ref.option"] 117 118# The rst_epilog fragment is effectively included in every rST file. 119# We use it to define substitutions based on build config that 120# can then be used in the documentation. The fallback if the 121# environment variable is not set is for the benefit of readthedocs 122# style document building; our Makefile always sets the variable. 123confdir = os.getenv('CONFDIR', "/etc/qemu") 124rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" 125 126# -- Options for HTML output ---------------------------------------------- 127 128# The theme to use for HTML and HTML Help pages. See the documentation for 129# a list of builtin themes. 130# 131html_theme = 'alabaster' 132 133# Theme options are theme-specific and customize the look and feel of a theme 134# further. For a list of options available for each theme, see the 135# documentation. 136# We initialize this to empty here, so the per-manual conf.py can just 137# add individual key/value entries. 138html_theme_options = { 139} 140 141# Add any paths that contain custom static files (such as style sheets) here, 142# relative to this directory. They are copied after the builtin static files, 143# so a file named "default.css" will overwrite the builtin "default.css". 144# QEMU doesn't yet have any static files, so comment this out so we don't 145# get a warning about a missing directory. 146# If we do ever add this then it would probably be better to call the 147# subdirectory sphinx_static, as the Linux kernel does. 148# html_static_path = ['_static'] 149 150# Custom sidebar templates, must be a dictionary that maps document names 151# to template names. 152# 153# This is required for the alabaster theme 154# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars 155html_sidebars = { 156 '**': [ 157 'about.html', 158 'navigation.html', 159 'searchbox.html', 160 ] 161} 162 163# Don't copy the rST source files to the HTML output directory, 164# and don't put links to the sources into the output HTML. 165html_copy_source = False 166 167# -- Options for HTMLHelp output ------------------------------------------ 168 169# Output file base name for HTML help builder. 170htmlhelp_basename = 'QEMUdoc' 171 172 173# -- Options for LaTeX output --------------------------------------------- 174 175latex_elements = { 176 # The paper size ('letterpaper' or 'a4paper'). 177 # 178 # 'papersize': 'letterpaper', 179 180 # The font size ('10pt', '11pt' or '12pt'). 181 # 182 # 'pointsize': '10pt', 183 184 # Additional stuff for the LaTeX preamble. 185 # 186 # 'preamble': '', 187 188 # Latex figure (float) alignment 189 # 190 # 'figure_align': 'htbp', 191} 192 193# Grouping the document tree into LaTeX files. List of tuples 194# (source start file, target name, title, 195# author, documentclass [howto, manual, or own class]). 196latex_documents = [ 197 (master_doc, 'QEMU.tex', u'QEMU Documentation', 198 u'The QEMU Project Developers', 'manual'), 199] 200 201 202# -- Options for manual page output --------------------------------------- 203# Individual manual/conf.py can override this to create man pages 204man_pages = [] 205 206# -- Options for Texinfo output ------------------------------------------- 207 208# Grouping the document tree into Texinfo files. List of tuples 209# (source start file, target name, title, author, 210# dir menu entry, description, category) 211texinfo_documents = [ 212 (master_doc, 'QEMU', u'QEMU Documentation', 213 author, 'QEMU', 'One line description of project.', 214 'Miscellaneous'), 215] 216 217 218 219# We use paths starting from qemu_docdir here so that you can run 220# sphinx-build from anywhere and the kerneldoc extension can still 221# find everything. 222kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc') 223kerneldoc_srctree = os.path.join(qemu_docdir, '..') 224hxtool_srctree = os.path.join(qemu_docdir, '..') 225