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 34f8cf7147SPeter Maydell# The per-manual conf.py will set qemu_docdir for a single-manual build; 35f8cf7147SPeter Maydell# otherwise set it here if this is an entire-manual-set build. 36f8cf7147SPeter Maydell# This is always the absolute path of the docs/ directory in the source tree. 37f8cf7147SPeter Maydelltry: 38f8cf7147SPeter Maydell qemu_docdir 39f8cf7147SPeter Maydellexcept NameError: 40f8cf7147SPeter Maydell qemu_docdir = os.path.abspath(".") 41f8cf7147SPeter Maydell 425329da6aSPeter Maydell# If extensions (or modules to document with autodoc) are in another directory, 435329da6aSPeter Maydell# add these directories to sys.path here. If the directory is relative to the 44f8cf7147SPeter Maydell# documentation root, use an absolute path starting from qemu_docdir. 455329da6aSPeter Maydell# 464078ee54SPeter Maydell# Our extensions are in docs/sphinx; the qapidoc extension requires 474078ee54SPeter Maydell# the QAPI modules from scripts/. 48cd231e13SJohn Snowsys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) 494078ee54SPeter Maydellsys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) 505329da6aSPeter Maydell 515329da6aSPeter Maydell 525329da6aSPeter Maydell# -- General configuration ------------------------------------------------ 535329da6aSPeter Maydell 545329da6aSPeter Maydell# If your documentation needs a minimal Sphinx version, state it here. 555329da6aSPeter Maydell# 56bf3f8573SPeter Maydell# Sphinx 1.5 and earlier can't build our docs because they are too 57bf3f8573SPeter Maydell# picky about the syntax of the argument to the option:: directive 58bf3f8573SPeter Maydell# (see Sphinx bugs #646, #3366). 59bf3f8573SPeter Maydellneeds_sphinx = '1.6' 605329da6aSPeter Maydell 615329da6aSPeter Maydell# Add any Sphinx extension module names here, as strings. They can be 625329da6aSPeter Maydell# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 635329da6aSPeter Maydell# ones. 644078ee54SPeter Maydellextensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc'] 655329da6aSPeter Maydell 662668dc7bSMarc-André Lureauif sphinx.version_info[:3] > (4, 0, 0): 672668dc7bSMarc-André Lureau tags.add('sphinx4') 682668dc7bSMarc-André Lureau extensions += ['dbusdoc'] 692668dc7bSMarc-André Lureauelse: 702668dc7bSMarc-André Lureau extensions += ['fakedbusdoc'] 712668dc7bSMarc-André Lureau 725329da6aSPeter Maydell# Add any paths that contain templates here, relative to this directory. 730dd35c16SMarc-André Lureautemplates_path = [os.path.join(qemu_docdir, '_templates')] 745329da6aSPeter Maydell 755329da6aSPeter Maydell# The suffix(es) of source filenames. 765329da6aSPeter Maydell# You can specify multiple suffix as a list of string: 775329da6aSPeter Maydell# 785329da6aSPeter Maydell# source_suffix = ['.rst', '.md'] 795329da6aSPeter Maydellsource_suffix = '.rst' 805329da6aSPeter Maydell 815329da6aSPeter Maydell# The master toctree document. 825329da6aSPeter Maydellmaster_doc = 'index' 835329da6aSPeter Maydell 84c11b3a1dSJohn Snow# Interpret `single-backticks` to be a cross-reference to any kind of 85c11b3a1dSJohn Snow# referenceable object. Unresolvable or ambiguous references will emit a 86c11b3a1dSJohn Snow# warning at build time. 87c11b3a1dSJohn Snowdefault_role = 'any' 88c11b3a1dSJohn Snow 895329da6aSPeter Maydell# General information about the project. 905329da6aSPeter Maydellproject = u'QEMU' 915dd6bfd9SAni Sinhacopyright = u'2024, The QEMU Project Developers' 925329da6aSPeter Maydellauthor = u'The QEMU Project Developers' 935329da6aSPeter Maydell 945329da6aSPeter Maydell# The version info for the project you're documenting, acts as replacement for 955329da6aSPeter Maydell# |version| and |release|, also used in various other places throughout the 965329da6aSPeter Maydell# built documents. 976038f5fcSPeter Maydell 986038f5fcSPeter Maydell# Extract this information from the VERSION file, for the benefit of 996038f5fcSPeter Maydell# standalone Sphinx runs as used by readthedocs.org. Builds run from 1006038f5fcSPeter Maydell# the Makefile will pass version and release on the sphinx-build 1016038f5fcSPeter Maydell# command line, which override this. 1026038f5fcSPeter Maydelltry: 1036038f5fcSPeter Maydell extracted_version = None 1046038f5fcSPeter Maydell with open(os.path.join(qemu_docdir, '../VERSION')) as f: 1056038f5fcSPeter Maydell extracted_version = f.readline().strip() 1066038f5fcSPeter Maydellexcept: 1076038f5fcSPeter Maydell pass 1086038f5fcSPeter Maydellfinally: 1096038f5fcSPeter Maydell if extracted_version: 1106038f5fcSPeter Maydell version = release = extracted_version 1116038f5fcSPeter Maydell else: 1126038f5fcSPeter Maydell version = release = "unknown version" 1135329da6aSPeter Maydell 1145329da6aSPeter Maydell# The language for content autogenerated by Sphinx. Refer to documentation 1155329da6aSPeter Maydell# for a list of supported languages. 1165329da6aSPeter Maydell# 1175329da6aSPeter Maydell# This is also used if you do content translation via gettext catalogs. 1185329da6aSPeter Maydell# Usually you set "language" from the command line for these cases. 119ba1a6723SMartin Liškalanguage = 'en' 1205329da6aSPeter Maydell 1215329da6aSPeter Maydell# List of patterns, relative to source directory, that match files and 1225329da6aSPeter Maydell# directories to ignore when looking for source files. 1235329da6aSPeter Maydell# This patterns also effect to html_static_path and html_extra_path 1245329da6aSPeter Maydellexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 1255329da6aSPeter Maydell 1265329da6aSPeter Maydell# The name of the Pygments (syntax highlighting) style to use. 1275329da6aSPeter Maydellpygments_style = 'sphinx' 1285329da6aSPeter Maydell 1295329da6aSPeter Maydell# If true, `todo` and `todoList` produce output, else they produce nothing. 1305329da6aSPeter Maydelltodo_include_todos = False 1315329da6aSPeter Maydell 132e250e867SPeter Maydell# Sphinx defaults to warning about use of :option: for options not defined 133e250e867SPeter Maydell# with "option::" in the document being processed. Turn that off. 134e250e867SPeter Maydellsuppress_warnings = ["ref.option"] 1355329da6aSPeter Maydell 13627a296fcSPeter Maydell# The rst_epilog fragment is effectively included in every rST file. 13727a296fcSPeter Maydell# We use it to define substitutions based on build config that 13827a296fcSPeter Maydell# can then be used in the documentation. The fallback if the 13927a296fcSPeter Maydell# environment variable is not set is for the benefit of readthedocs 14027a296fcSPeter Maydell# style document building; our Makefile always sets the variable. 14127a296fcSPeter Maydellconfdir = os.getenv('CONFDIR', "/etc/qemu") 14227a296fcSPeter Maydellrst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" 143de1572caSPeter Maydell# We slurp in the defs.rst.inc and literally include it into rst_epilog, 144de1572caSPeter Maydell# because Sphinx's include:: directive doesn't work with absolute paths 145de1572caSPeter Maydell# and there isn't any one single relative path that will work for all 146de1572caSPeter Maydell# documents and for both via-make and direct sphinx-build invocation. 147de1572caSPeter Maydellwith open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: 148de1572caSPeter Maydell rst_epilog += f.read() 14927a296fcSPeter Maydell 1505329da6aSPeter Maydell# -- Options for HTML output ---------------------------------------------- 1515329da6aSPeter Maydell 1525329da6aSPeter Maydell# The theme to use for HTML and HTML Help pages. See the documentation for 1535329da6aSPeter Maydell# a list of builtin themes. 1545329da6aSPeter Maydell# 15573e6aec6SMarc-André Lureautry: 15673e6aec6SMarc-André Lureau import sphinx_rtd_theme 15773e6aec6SMarc-André Lureauexcept ImportError: 15873e6aec6SMarc-André Lureau raise ConfigError( 15973e6aec6SMarc-André Lureau 'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n' 16073e6aec6SMarc-André Lureau ) 16173e6aec6SMarc-André Lureau 16273e6aec6SMarc-André Lureauhtml_theme = 'sphinx_rtd_theme' 1635329da6aSPeter Maydell 1645329da6aSPeter Maydell# Theme options are theme-specific and customize the look and feel of a theme 1655329da6aSPeter Maydell# further. For a list of options available for each theme, see the 1665329da6aSPeter Maydell# documentation. 167f8cf7147SPeter Maydellhtml_theme_options = { 16873e6aec6SMarc-André Lureau "style_nav_header_background": "#802400", 16996871b38SMarc-André Lureau "navigation_with_keys": True, 170f8cf7147SPeter Maydell} 1715329da6aSPeter Maydell 17273e6aec6SMarc-André Lureauhtml_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png") 17373e6aec6SMarc-André Lureau 17473e6aec6SMarc-André Lureauhtml_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png") 17573e6aec6SMarc-André Lureau 1765329da6aSPeter Maydell# Add any paths that contain custom static files (such as style sheets) here, 1775329da6aSPeter Maydell# relative to this directory. They are copied after the builtin static files, 1785329da6aSPeter Maydell# so a file named "default.css" will overwrite the builtin "default.css". 17973e6aec6SMarc-André Lureauhtml_static_path = [os.path.join(qemu_docdir, "sphinx-static")] 18073e6aec6SMarc-André Lureau 18173e6aec6SMarc-André Lureauhtml_css_files = [ 18273e6aec6SMarc-André Lureau 'theme_overrides.css', 18373e6aec6SMarc-André Lureau] 18473e6aec6SMarc-André Lureau 18594237516SMarc-André Lureauhtml_js_files = [ 18694237516SMarc-André Lureau 'custom.js', 18794237516SMarc-André Lureau] 18894237516SMarc-André Lureau 18973e6aec6SMarc-André Lureauhtml_context = { 19073e6aec6SMarc-André Lureau "display_gitlab": True, 19173e6aec6SMarc-André Lureau "gitlab_user": "qemu-project", 19273e6aec6SMarc-André Lureau "gitlab_repo": "qemu", 19373e6aec6SMarc-André Lureau "gitlab_version": "master", 19473e6aec6SMarc-André Lureau "conf_py_path": "/docs/", # Path in the checkout to the docs root 19573e6aec6SMarc-André Lureau} 1965329da6aSPeter Maydell 1975329da6aSPeter Maydell# Custom sidebar templates, must be a dictionary that maps document names 1985329da6aSPeter Maydell# to template names. 19973e6aec6SMarc-André Lureau#html_sidebars = {} 2005329da6aSPeter Maydell 201479fb8a5SPeter Maydell# Don't copy the rST source files to the HTML output directory, 202479fb8a5SPeter Maydell# and don't put links to the sources into the output HTML. 203479fb8a5SPeter Maydellhtml_copy_source = False 2045329da6aSPeter Maydell 2055329da6aSPeter Maydell# -- Options for HTMLHelp output ------------------------------------------ 2065329da6aSPeter Maydell 2075329da6aSPeter Maydell# Output file base name for HTML help builder. 2085329da6aSPeter Maydellhtmlhelp_basename = 'QEMUdoc' 2095329da6aSPeter Maydell 2105329da6aSPeter Maydell 2115329da6aSPeter Maydell# -- Options for LaTeX output --------------------------------------------- 2125329da6aSPeter Maydell 2135329da6aSPeter Maydelllatex_elements = { 2145329da6aSPeter Maydell # The paper size ('letterpaper' or 'a4paper'). 2155329da6aSPeter Maydell # 2165329da6aSPeter Maydell # 'papersize': 'letterpaper', 2175329da6aSPeter Maydell 2185329da6aSPeter Maydell # The font size ('10pt', '11pt' or '12pt'). 2195329da6aSPeter Maydell # 2205329da6aSPeter Maydell # 'pointsize': '10pt', 2215329da6aSPeter Maydell 2225329da6aSPeter Maydell # Additional stuff for the LaTeX preamble. 2235329da6aSPeter Maydell # 2245329da6aSPeter Maydell # 'preamble': '', 2255329da6aSPeter Maydell 2265329da6aSPeter Maydell # Latex figure (float) alignment 2275329da6aSPeter Maydell # 2285329da6aSPeter Maydell # 'figure_align': 'htbp', 2295329da6aSPeter Maydell} 2305329da6aSPeter Maydell 2315329da6aSPeter Maydell# Grouping the document tree into LaTeX files. List of tuples 2325329da6aSPeter Maydell# (source start file, target name, title, 2335329da6aSPeter Maydell# author, documentclass [howto, manual, or own class]). 2345329da6aSPeter Maydelllatex_documents = [ 2355329da6aSPeter Maydell (master_doc, 'QEMU.tex', u'QEMU Documentation', 2365329da6aSPeter Maydell u'The QEMU Project Developers', 'manual'), 2375329da6aSPeter Maydell] 2385329da6aSPeter Maydell 2395329da6aSPeter Maydell 2405329da6aSPeter Maydell# -- Options for manual page output --------------------------------------- 24127a296fcSPeter Maydell# Individual manual/conf.py can override this to create man pages 242b93f4fbdSPeter Maydellman_pages = [ 243b93f4fbdSPeter Maydell ('interop/qemu-ga', 'qemu-ga', 244b93f4fbdSPeter Maydell 'QEMU Guest Agent', 245b93f4fbdSPeter Maydell ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8), 246b93f4fbdSPeter Maydell ('interop/qemu-ga-ref', 'qemu-ga-ref', 247b93f4fbdSPeter Maydell 'QEMU Guest Agent Protocol Reference', 248b93f4fbdSPeter Maydell [], 7), 249b93f4fbdSPeter Maydell ('interop/qemu-qmp-ref', 'qemu-qmp-ref', 250b93f4fbdSPeter Maydell 'QEMU QMP Reference Manual', 251b93f4fbdSPeter Maydell [], 7), 252b93f4fbdSPeter Maydell ('interop/qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref', 253b93f4fbdSPeter Maydell 'QEMU Storage Daemon QMP Reference Manual', 254b93f4fbdSPeter Maydell [], 7), 255b93f4fbdSPeter Maydell ('system/qemu-manpage', 'qemu', 256b93f4fbdSPeter Maydell 'QEMU User Documentation', 257b93f4fbdSPeter Maydell ['Fabrice Bellard'], 1), 258b93f4fbdSPeter Maydell ('system/qemu-block-drivers', 'qemu-block-drivers', 259b93f4fbdSPeter Maydell 'QEMU block drivers reference', 260b93f4fbdSPeter Maydell ['Fabrice Bellard and the QEMU Project developers'], 7), 261b93f4fbdSPeter Maydell ('system/qemu-cpu-models', 'qemu-cpu-models', 262b93f4fbdSPeter Maydell 'QEMU CPU Models', 263b93f4fbdSPeter Maydell ['The QEMU Project developers'], 7), 264b93f4fbdSPeter Maydell ('tools/qemu-img', 'qemu-img', 265b93f4fbdSPeter Maydell 'QEMU disk image utility', 266b93f4fbdSPeter Maydell ['Fabrice Bellard'], 1), 267b93f4fbdSPeter Maydell ('tools/qemu-nbd', 'qemu-nbd', 268b93f4fbdSPeter Maydell 'QEMU Disk Network Block Device Server', 269b93f4fbdSPeter Maydell ['Anthony Liguori <anthony@codemonkey.ws>'], 8), 270b93f4fbdSPeter Maydell ('tools/qemu-pr-helper', 'qemu-pr-helper', 271b93f4fbdSPeter Maydell 'QEMU persistent reservation helper', 272b93f4fbdSPeter Maydell [], 8), 273b93f4fbdSPeter Maydell ('tools/qemu-storage-daemon', 'qemu-storage-daemon', 274b93f4fbdSPeter Maydell 'QEMU storage daemon', 275b93f4fbdSPeter Maydell [], 1), 276b93f4fbdSPeter Maydell ('tools/qemu-trace-stap', 'qemu-trace-stap', 277b93f4fbdSPeter Maydell 'QEMU SystemTap trace tool', 278b93f4fbdSPeter Maydell [], 1), 279b93f4fbdSPeter Maydell ('tools/virtfs-proxy-helper', 'virtfs-proxy-helper', 280b93f4fbdSPeter Maydell 'QEMU 9p virtfs proxy filesystem helper', 281b93f4fbdSPeter Maydell ['M. Mohan Kumar'], 1), 282b93f4fbdSPeter Maydell] 283269a7e97SDamien Goutte-Gattatman_make_section_directory = False 2845329da6aSPeter Maydell 28522b5ea75SPeter Maydell# We use paths starting from qemu_docdir here so that you can run 28622b5ea75SPeter Maydell# sphinx-build from anywhere and the kerneldoc extension can still 28722b5ea75SPeter Maydell# find everything. 288a94a689cSYonggang Luokerneldoc_bin = ['perl', os.path.join(qemu_docdir, '../scripts/kernel-doc')] 28922b5ea75SPeter Maydellkerneldoc_srctree = os.path.join(qemu_docdir, '..') 2906803d6e9SPeter Maydellhxtool_srctree = os.path.join(qemu_docdir, '..') 2914078ee54SPeter Maydellqapidoc_srctree = os.path.join(qemu_docdir, '..') 2922668dc7bSMarc-André Lureaudbusdoc_srctree = os.path.join(qemu_docdir, '..') 2932668dc7bSMarc-André Lureaudbus_index_common_prefix = ["org.qemu."] 294