15329da6aSPeter Maydell# -*- coding: utf-8 -*- 25329da6aSPeter Maydell# 35329da6aSPeter Maydell# QEMU documentation build configuration file, created by 45329da6aSPeter Maydell# sphinx-quickstart on Thu Jan 31 16:40:14 2019. 55329da6aSPeter Maydell# 6f8cf7147SPeter Maydell# This config file can be used in one of two ways: 7f8cf7147SPeter Maydell# (1) as a common config file which is included by the conf.py 8f8cf7147SPeter Maydell# for each of QEMU's manuals: in this case sphinx-build is run multiple 9f8cf7147SPeter Maydell# times, once per subdirectory. 10f8cf7147SPeter Maydell# (2) as a top level conf file which will result in building all 11f8cf7147SPeter Maydell# the manuals into a single document: in this case sphinx-build is 12f8cf7147SPeter Maydell# run once, on the top-level docs directory. 13f8cf7147SPeter Maydell# 14f8cf7147SPeter Maydell# QEMU's makefiles take option (1), which allows us to install 15f8cf7147SPeter Maydell# only the ones the user cares about (in particular we don't want 16f8cf7147SPeter Maydell# to ship the 'devel' manual to end-users). 17f8cf7147SPeter Maydell# Third-party sites such as readthedocs.org will take option (2). 18f8cf7147SPeter Maydell# 19f8cf7147SPeter Maydell# 205329da6aSPeter Maydell# This file is execfile()d with the current directory set to its 215329da6aSPeter Maydell# containing dir. 225329da6aSPeter Maydell# 235329da6aSPeter Maydell# Note that not all possible configuration values are present in this 245329da6aSPeter Maydell# autogenerated file. 255329da6aSPeter Maydell# 265329da6aSPeter Maydell# All configuration values have a default; values that are commented out 275329da6aSPeter Maydell# serve to show the default. 285329da6aSPeter Maydell 29f8cf7147SPeter Maydellimport os 30f8cf7147SPeter Maydellimport sys 31758b617aSPeter Maydellimport sphinx 32e22684e3SPeter Maydellfrom sphinx.errors import ConfigError 33758b617aSPeter Maydell 34758b617aSPeter Maydell# Make Sphinx fail cleanly if using an old Python, rather than obscurely 35758b617aSPeter Maydell# failing because some code in one of our extensions doesn't work there. 36e22684e3SPeter Maydell# In newer versions of Sphinx this will display nicely; in older versions 37e22684e3SPeter Maydell# Sphinx will also produce a Python backtrace but at least the information 38e22684e3SPeter Maydell# gets printed... 391b11f28dSThomas Huthif sys.version_info < (3,6): 40e22684e3SPeter Maydell raise ConfigError( 411b11f28dSThomas Huth "QEMU requires a Sphinx that uses Python 3.6 or better\n") 42f8cf7147SPeter Maydell 43f8cf7147SPeter Maydell# The per-manual conf.py will set qemu_docdir for a single-manual build; 44f8cf7147SPeter Maydell# otherwise set it here if this is an entire-manual-set build. 45f8cf7147SPeter Maydell# This is always the absolute path of the docs/ directory in the source tree. 46f8cf7147SPeter Maydelltry: 47f8cf7147SPeter Maydell qemu_docdir 48f8cf7147SPeter Maydellexcept NameError: 49f8cf7147SPeter Maydell qemu_docdir = os.path.abspath(".") 50f8cf7147SPeter Maydell 515329da6aSPeter Maydell# If extensions (or modules to document with autodoc) are in another directory, 525329da6aSPeter Maydell# add these directories to sys.path here. If the directory is relative to the 53f8cf7147SPeter Maydell# documentation root, use an absolute path starting from qemu_docdir. 545329da6aSPeter Maydell# 554078ee54SPeter Maydell# Our extensions are in docs/sphinx; the qapidoc extension requires 564078ee54SPeter Maydell# the QAPI modules from scripts/. 57cd231e13SJohn Snowsys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) 584078ee54SPeter Maydellsys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) 595329da6aSPeter Maydell 605329da6aSPeter Maydell 615329da6aSPeter Maydell# -- General configuration ------------------------------------------------ 625329da6aSPeter Maydell 635329da6aSPeter Maydell# If your documentation needs a minimal Sphinx version, state it here. 645329da6aSPeter Maydell# 65bf3f8573SPeter Maydell# Sphinx 1.5 and earlier can't build our docs because they are too 66bf3f8573SPeter Maydell# picky about the syntax of the argument to the option:: directive 67bf3f8573SPeter Maydell# (see Sphinx bugs #646, #3366). 68bf3f8573SPeter Maydellneeds_sphinx = '1.6' 695329da6aSPeter Maydell 705329da6aSPeter Maydell# Add any Sphinx extension module names here, as strings. They can be 715329da6aSPeter Maydell# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 725329da6aSPeter Maydell# ones. 734078ee54SPeter Maydellextensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc'] 745329da6aSPeter Maydell 755329da6aSPeter Maydell# Add any paths that contain templates here, relative to this directory. 765329da6aSPeter Maydelltemplates_path = ['_templates'] 775329da6aSPeter Maydell 785329da6aSPeter Maydell# The suffix(es) of source filenames. 795329da6aSPeter Maydell# You can specify multiple suffix as a list of string: 805329da6aSPeter Maydell# 815329da6aSPeter Maydell# source_suffix = ['.rst', '.md'] 825329da6aSPeter Maydellsource_suffix = '.rst' 835329da6aSPeter Maydell 845329da6aSPeter Maydell# The master toctree document. 855329da6aSPeter Maydellmaster_doc = 'index' 865329da6aSPeter Maydell 875329da6aSPeter Maydell# General information about the project. 885329da6aSPeter Maydellproject = u'QEMU' 899b26a610SPeter Maydellcopyright = u'2020, The QEMU Project Developers' 905329da6aSPeter Maydellauthor = u'The QEMU Project Developers' 915329da6aSPeter Maydell 925329da6aSPeter Maydell# The version info for the project you're documenting, acts as replacement for 935329da6aSPeter Maydell# |version| and |release|, also used in various other places throughout the 945329da6aSPeter Maydell# built documents. 956038f5fcSPeter Maydell 966038f5fcSPeter Maydell# Extract this information from the VERSION file, for the benefit of 976038f5fcSPeter Maydell# standalone Sphinx runs as used by readthedocs.org. Builds run from 986038f5fcSPeter Maydell# the Makefile will pass version and release on the sphinx-build 996038f5fcSPeter Maydell# command line, which override this. 1006038f5fcSPeter Maydelltry: 1016038f5fcSPeter Maydell extracted_version = None 1026038f5fcSPeter Maydell with open(os.path.join(qemu_docdir, '../VERSION')) as f: 1036038f5fcSPeter Maydell extracted_version = f.readline().strip() 1046038f5fcSPeter Maydellexcept: 1056038f5fcSPeter Maydell pass 1066038f5fcSPeter Maydellfinally: 1076038f5fcSPeter Maydell if extracted_version: 1086038f5fcSPeter Maydell version = release = extracted_version 1096038f5fcSPeter Maydell else: 1106038f5fcSPeter Maydell version = release = "unknown version" 1115329da6aSPeter Maydell 1125329da6aSPeter Maydell# The language for content autogenerated by Sphinx. Refer to documentation 1135329da6aSPeter Maydell# for a list of supported languages. 1145329da6aSPeter Maydell# 1155329da6aSPeter Maydell# This is also used if you do content translation via gettext catalogs. 1165329da6aSPeter Maydell# Usually you set "language" from the command line for these cases. 1175329da6aSPeter Maydelllanguage = None 1185329da6aSPeter Maydell 1195329da6aSPeter Maydell# List of patterns, relative to source directory, that match files and 1205329da6aSPeter Maydell# directories to ignore when looking for source files. 1215329da6aSPeter Maydell# This patterns also effect to html_static_path and html_extra_path 1225329da6aSPeter Maydellexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 1235329da6aSPeter Maydell 1245329da6aSPeter Maydell# The name of the Pygments (syntax highlighting) style to use. 1255329da6aSPeter Maydellpygments_style = 'sphinx' 1265329da6aSPeter Maydell 1275329da6aSPeter Maydell# If true, `todo` and `todoList` produce output, else they produce nothing. 1285329da6aSPeter Maydelltodo_include_todos = False 1295329da6aSPeter Maydell 130e250e867SPeter Maydell# Sphinx defaults to warning about use of :option: for options not defined 131e250e867SPeter Maydell# with "option::" in the document being processed. Turn that off. 132e250e867SPeter Maydellsuppress_warnings = ["ref.option"] 1335329da6aSPeter Maydell 13427a296fcSPeter Maydell# The rst_epilog fragment is effectively included in every rST file. 13527a296fcSPeter Maydell# We use it to define substitutions based on build config that 13627a296fcSPeter Maydell# can then be used in the documentation. The fallback if the 13727a296fcSPeter Maydell# environment variable is not set is for the benefit of readthedocs 13827a296fcSPeter Maydell# style document building; our Makefile always sets the variable. 13927a296fcSPeter Maydellconfdir = os.getenv('CONFDIR', "/etc/qemu") 14027a296fcSPeter Maydellrst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" 141de1572caSPeter Maydell# We slurp in the defs.rst.inc and literally include it into rst_epilog, 142de1572caSPeter Maydell# because Sphinx's include:: directive doesn't work with absolute paths 143de1572caSPeter Maydell# and there isn't any one single relative path that will work for all 144de1572caSPeter Maydell# documents and for both via-make and direct sphinx-build invocation. 145de1572caSPeter Maydellwith open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: 146de1572caSPeter Maydell rst_epilog += f.read() 14727a296fcSPeter Maydell 1485329da6aSPeter Maydell# -- Options for HTML output ---------------------------------------------- 1495329da6aSPeter Maydell 1505329da6aSPeter Maydell# The theme to use for HTML and HTML Help pages. See the documentation for 1515329da6aSPeter Maydell# a list of builtin themes. 1525329da6aSPeter Maydell# 1535329da6aSPeter Maydellhtml_theme = 'alabaster' 1545329da6aSPeter Maydell 1555329da6aSPeter Maydell# Theme options are theme-specific and customize the look and feel of a theme 1565329da6aSPeter Maydell# further. For a list of options available for each theme, see the 1575329da6aSPeter Maydell# documentation. 158f8cf7147SPeter Maydell# We initialize this to empty here, so the per-manual conf.py can just 159f8cf7147SPeter Maydell# add individual key/value entries. 160f8cf7147SPeter Maydellhtml_theme_options = { 161f8cf7147SPeter Maydell} 1625329da6aSPeter Maydell 1635329da6aSPeter Maydell# Add any paths that contain custom static files (such as style sheets) here, 1645329da6aSPeter Maydell# relative to this directory. They are copied after the builtin static files, 1655329da6aSPeter Maydell# so a file named "default.css" will overwrite the builtin "default.css". 16607fd6563SPeter Maydell# QEMU doesn't yet have any static files, so comment this out so we don't 16707fd6563SPeter Maydell# get a warning about a missing directory. 16807fd6563SPeter Maydell# If we do ever add this then it would probably be better to call the 16907fd6563SPeter Maydell# subdirectory sphinx_static, as the Linux kernel does. 17007fd6563SPeter Maydell# html_static_path = ['_static'] 1715329da6aSPeter Maydell 1725329da6aSPeter Maydell# Custom sidebar templates, must be a dictionary that maps document names 1735329da6aSPeter Maydell# to template names. 1745329da6aSPeter Maydell# 1755329da6aSPeter Maydell# This is required for the alabaster theme 1765329da6aSPeter Maydell# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars 1775329da6aSPeter Maydellhtml_sidebars = { 1785329da6aSPeter Maydell '**': [ 1794fad3864SPeter Maydell 'about.html', 180704a256dSDaniel P. Berrangé 'editpage.html', 1814fad3864SPeter Maydell 'navigation.html', 1825329da6aSPeter Maydell 'searchbox.html', 1835329da6aSPeter Maydell ] 1845329da6aSPeter Maydell} 1855329da6aSPeter Maydell 186479fb8a5SPeter Maydell# Don't copy the rST source files to the HTML output directory, 187479fb8a5SPeter Maydell# and don't put links to the sources into the output HTML. 188479fb8a5SPeter Maydellhtml_copy_source = False 1895329da6aSPeter Maydell 1905329da6aSPeter Maydell# -- Options for HTMLHelp output ------------------------------------------ 1915329da6aSPeter Maydell 1925329da6aSPeter Maydell# Output file base name for HTML help builder. 1935329da6aSPeter Maydellhtmlhelp_basename = 'QEMUdoc' 1945329da6aSPeter Maydell 1955329da6aSPeter Maydell 1965329da6aSPeter Maydell# -- Options for LaTeX output --------------------------------------------- 1975329da6aSPeter Maydell 1985329da6aSPeter Maydelllatex_elements = { 1995329da6aSPeter Maydell # The paper size ('letterpaper' or 'a4paper'). 2005329da6aSPeter Maydell # 2015329da6aSPeter Maydell # 'papersize': 'letterpaper', 2025329da6aSPeter Maydell 2035329da6aSPeter Maydell # The font size ('10pt', '11pt' or '12pt'). 2045329da6aSPeter Maydell # 2055329da6aSPeter Maydell # 'pointsize': '10pt', 2065329da6aSPeter Maydell 2075329da6aSPeter Maydell # Additional stuff for the LaTeX preamble. 2085329da6aSPeter Maydell # 2095329da6aSPeter Maydell # 'preamble': '', 2105329da6aSPeter Maydell 2115329da6aSPeter Maydell # Latex figure (float) alignment 2125329da6aSPeter Maydell # 2135329da6aSPeter Maydell # 'figure_align': 'htbp', 2145329da6aSPeter Maydell} 2155329da6aSPeter Maydell 2165329da6aSPeter Maydell# Grouping the document tree into LaTeX files. List of tuples 2175329da6aSPeter Maydell# (source start file, target name, title, 2185329da6aSPeter Maydell# author, documentclass [howto, manual, or own class]). 2195329da6aSPeter Maydelllatex_documents = [ 2205329da6aSPeter Maydell (master_doc, 'QEMU.tex', u'QEMU Documentation', 2215329da6aSPeter Maydell u'The QEMU Project Developers', 'manual'), 2225329da6aSPeter Maydell] 2235329da6aSPeter Maydell 2245329da6aSPeter Maydell 2255329da6aSPeter Maydell# -- Options for manual page output --------------------------------------- 22627a296fcSPeter Maydell# Individual manual/conf.py can override this to create man pages 227*b93f4fbdSPeter Maydellman_pages = [ 228*b93f4fbdSPeter Maydell ('interop/qemu-ga', 'qemu-ga', 229*b93f4fbdSPeter Maydell 'QEMU Guest Agent', 230*b93f4fbdSPeter Maydell ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8), 231*b93f4fbdSPeter Maydell ('interop/qemu-ga-ref', 'qemu-ga-ref', 232*b93f4fbdSPeter Maydell 'QEMU Guest Agent Protocol Reference', 233*b93f4fbdSPeter Maydell [], 7), 234*b93f4fbdSPeter Maydell ('interop/qemu-qmp-ref', 'qemu-qmp-ref', 235*b93f4fbdSPeter Maydell 'QEMU QMP Reference Manual', 236*b93f4fbdSPeter Maydell [], 7), 237*b93f4fbdSPeter Maydell ('interop/qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref', 238*b93f4fbdSPeter Maydell 'QEMU Storage Daemon QMP Reference Manual', 239*b93f4fbdSPeter Maydell [], 7), 240*b93f4fbdSPeter Maydell ('system/qemu-manpage', 'qemu', 241*b93f4fbdSPeter Maydell 'QEMU User Documentation', 242*b93f4fbdSPeter Maydell ['Fabrice Bellard'], 1), 243*b93f4fbdSPeter Maydell ('system/qemu-block-drivers', 'qemu-block-drivers', 244*b93f4fbdSPeter Maydell 'QEMU block drivers reference', 245*b93f4fbdSPeter Maydell ['Fabrice Bellard and the QEMU Project developers'], 7), 246*b93f4fbdSPeter Maydell ('system/qemu-cpu-models', 'qemu-cpu-models', 247*b93f4fbdSPeter Maydell 'QEMU CPU Models', 248*b93f4fbdSPeter Maydell ['The QEMU Project developers'], 7), 249*b93f4fbdSPeter Maydell ('tools/qemu-img', 'qemu-img', 250*b93f4fbdSPeter Maydell 'QEMU disk image utility', 251*b93f4fbdSPeter Maydell ['Fabrice Bellard'], 1), 252*b93f4fbdSPeter Maydell ('tools/qemu-nbd', 'qemu-nbd', 253*b93f4fbdSPeter Maydell 'QEMU Disk Network Block Device Server', 254*b93f4fbdSPeter Maydell ['Anthony Liguori <anthony@codemonkey.ws>'], 8), 255*b93f4fbdSPeter Maydell ('tools/qemu-pr-helper', 'qemu-pr-helper', 256*b93f4fbdSPeter Maydell 'QEMU persistent reservation helper', 257*b93f4fbdSPeter Maydell [], 8), 258*b93f4fbdSPeter Maydell ('tools/qemu-storage-daemon', 'qemu-storage-daemon', 259*b93f4fbdSPeter Maydell 'QEMU storage daemon', 260*b93f4fbdSPeter Maydell [], 1), 261*b93f4fbdSPeter Maydell ('tools/qemu-trace-stap', 'qemu-trace-stap', 262*b93f4fbdSPeter Maydell 'QEMU SystemTap trace tool', 263*b93f4fbdSPeter Maydell [], 1), 264*b93f4fbdSPeter Maydell ('tools/virtfs-proxy-helper', 'virtfs-proxy-helper', 265*b93f4fbdSPeter Maydell 'QEMU 9p virtfs proxy filesystem helper', 266*b93f4fbdSPeter Maydell ['M. Mohan Kumar'], 1), 267*b93f4fbdSPeter Maydell ('tools/virtiofsd', 'virtiofsd', 268*b93f4fbdSPeter Maydell 'QEMU virtio-fs shared file system daemon', 269*b93f4fbdSPeter Maydell ['Stefan Hajnoczi <stefanha@redhat.com>', 270*b93f4fbdSPeter Maydell 'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1), 271*b93f4fbdSPeter Maydell] 2725329da6aSPeter Maydell 2735329da6aSPeter Maydell# -- Options for Texinfo output ------------------------------------------- 2745329da6aSPeter Maydell 2755329da6aSPeter Maydell# Grouping the document tree into Texinfo files. List of tuples 2765329da6aSPeter Maydell# (source start file, target name, title, author, 2775329da6aSPeter Maydell# dir menu entry, description, category) 2785329da6aSPeter Maydelltexinfo_documents = [ 2795329da6aSPeter Maydell (master_doc, 'QEMU', u'QEMU Documentation', 2805329da6aSPeter Maydell author, 'QEMU', 'One line description of project.', 2815329da6aSPeter Maydell 'Miscellaneous'), 2825329da6aSPeter Maydell] 2835329da6aSPeter Maydell 2845329da6aSPeter Maydell 2855329da6aSPeter Maydell 28622b5ea75SPeter Maydell# We use paths starting from qemu_docdir here so that you can run 28722b5ea75SPeter Maydell# sphinx-build from anywhere and the kerneldoc extension can still 28822b5ea75SPeter Maydell# find everything. 289a94a689cSYonggang Luokerneldoc_bin = ['perl', os.path.join(qemu_docdir, '../scripts/kernel-doc')] 29022b5ea75SPeter Maydellkerneldoc_srctree = os.path.join(qemu_docdir, '..') 2916803d6e9SPeter Maydellhxtool_srctree = os.path.join(qemu_docdir, '..') 2924078ee54SPeter Maydellqapidoc_srctree = os.path.join(qemu_docdir, '..') 293