conf.py (11442B)
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 29 import os 30 import sys 31 import sphinx 32 from distutils.version import LooseVersion 33 from sphinx.errors import ConfigError 34 35 # Make Sphinx fail cleanly if using an old Python, rather than obscurely 36 # failing because some code in one of our extensions doesn't work there. 37 # In newer versions of Sphinx this will display nicely; in older versions 38 # Sphinx will also produce a Python backtrace but at least the information 39 # gets printed... 40 if sys.version_info < (3,6): 41 raise ConfigError( 42 "QEMU requires a Sphinx that uses Python 3.6 or better\n") 43 44 # The per-manual conf.py will set qemu_docdir for a single-manual build; 45 # otherwise set it here if this is an entire-manual-set build. 46 # This is always the absolute path of the docs/ directory in the source tree. 47 try: 48 qemu_docdir 49 except NameError: 50 qemu_docdir = os.path.abspath(".") 51 52 # If extensions (or modules to document with autodoc) are in another directory, 53 # add these directories to sys.path here. If the directory is relative to the 54 # documentation root, use an absolute path starting from qemu_docdir. 55 # 56 # Our extensions are in docs/sphinx; the qapidoc extension requires 57 # the QAPI modules from scripts/. 58 sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) 59 sys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) 60 61 62 # -- General configuration ------------------------------------------------ 63 64 # If your documentation needs a minimal Sphinx version, state it here. 65 # 66 # Sphinx 1.5 and earlier can't build our docs because they are too 67 # picky about the syntax of the argument to the option:: directive 68 # (see Sphinx bugs #646, #3366). 69 needs_sphinx = '1.6' 70 71 # Add any Sphinx extension module names here, as strings. They can be 72 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 73 # ones. 74 extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc'] 75 76 if sphinx.version_info[:3] > (4, 0, 0): 77 tags.add('sphinx4') 78 extensions += ['dbusdoc'] 79 else: 80 extensions += ['fakedbusdoc'] 81 82 # Add any paths that contain templates here, relative to this directory. 83 templates_path = [os.path.join(qemu_docdir, '_templates')] 84 85 # The suffix(es) of source filenames. 86 # You can specify multiple suffix as a list of string: 87 # 88 # source_suffix = ['.rst', '.md'] 89 source_suffix = '.rst' 90 91 # The master toctree document. 92 master_doc = 'index' 93 94 # Interpret `single-backticks` to be a cross-reference to any kind of 95 # referenceable object. Unresolvable or ambiguous references will emit a 96 # warning at build time. 97 default_role = 'any' 98 99 # General information about the project. 100 project = u'QEMU' 101 copyright = u'2022, The QEMU Project Developers' 102 author = u'The QEMU Project Developers' 103 104 # The version info for the project you're documenting, acts as replacement for 105 # |version| and |release|, also used in various other places throughout the 106 # built documents. 107 108 # Extract this information from the VERSION file, for the benefit of 109 # standalone Sphinx runs as used by readthedocs.org. Builds run from 110 # the Makefile will pass version and release on the sphinx-build 111 # command line, which override this. 112 try: 113 extracted_version = None 114 with open(os.path.join(qemu_docdir, '../VERSION')) as f: 115 extracted_version = f.readline().strip() 116 except: 117 pass 118 finally: 119 if extracted_version: 120 version = release = extracted_version 121 else: 122 version = release = "unknown version" 123 124 # The language for content autogenerated by Sphinx. Refer to documentation 125 # for a list of supported languages. 126 # 127 # This is also used if you do content translation via gettext catalogs. 128 # Usually you set "language" from the command line for these cases. 129 language = 'en' 130 131 # List of patterns, relative to source directory, that match files and 132 # directories to ignore when looking for source files. 133 # This patterns also effect to html_static_path and html_extra_path 134 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 135 136 # The name of the Pygments (syntax highlighting) style to use. 137 pygments_style = 'sphinx' 138 139 # If true, `todo` and `todoList` produce output, else they produce nothing. 140 todo_include_todos = False 141 142 # Sphinx defaults to warning about use of :option: for options not defined 143 # with "option::" in the document being processed. Turn that off. 144 suppress_warnings = ["ref.option"] 145 146 # The rst_epilog fragment is effectively included in every rST file. 147 # We use it to define substitutions based on build config that 148 # can then be used in the documentation. The fallback if the 149 # environment variable is not set is for the benefit of readthedocs 150 # style document building; our Makefile always sets the variable. 151 confdir = os.getenv('CONFDIR', "/etc/qemu") 152 rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" 153 # We slurp in the defs.rst.inc and literally include it into rst_epilog, 154 # because Sphinx's include:: directive doesn't work with absolute paths 155 # and there isn't any one single relative path that will work for all 156 # documents and for both via-make and direct sphinx-build invocation. 157 with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f: 158 rst_epilog += f.read() 159 160 # -- Options for HTML output ---------------------------------------------- 161 162 # The theme to use for HTML and HTML Help pages. See the documentation for 163 # a list of builtin themes. 164 # 165 try: 166 import sphinx_rtd_theme 167 except ImportError: 168 raise ConfigError( 169 'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n' 170 ) 171 172 html_theme = 'sphinx_rtd_theme' 173 174 # Theme options are theme-specific and customize the look and feel of a theme 175 # further. For a list of options available for each theme, see the 176 # documentation. 177 if LooseVersion(sphinx_rtd_theme.__version__) >= LooseVersion("0.4.3"): 178 html_theme_options = { 179 "style_nav_header_background": "#802400", 180 "navigation_with_keys": True, 181 } 182 183 html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png") 184 185 html_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png") 186 187 # Add any paths that contain custom static files (such as style sheets) here, 188 # relative to this directory. They are copied after the builtin static files, 189 # so a file named "default.css" will overwrite the builtin "default.css". 190 html_static_path = [os.path.join(qemu_docdir, "sphinx-static")] 191 192 html_css_files = [ 193 'theme_overrides.css', 194 ] 195 196 html_js_files = [ 197 'custom.js', 198 ] 199 200 html_context = { 201 "display_gitlab": True, 202 "gitlab_user": "qemu-project", 203 "gitlab_repo": "qemu", 204 "gitlab_version": "master", 205 "conf_py_path": "/docs/", # Path in the checkout to the docs root 206 } 207 208 # Custom sidebar templates, must be a dictionary that maps document names 209 # to template names. 210 #html_sidebars = {} 211 212 # Don't copy the rST source files to the HTML output directory, 213 # and don't put links to the sources into the output HTML. 214 html_copy_source = False 215 216 # -- Options for HTMLHelp output ------------------------------------------ 217 218 # Output file base name for HTML help builder. 219 htmlhelp_basename = 'QEMUdoc' 220 221 222 # -- Options for LaTeX output --------------------------------------------- 223 224 latex_elements = { 225 # The paper size ('letterpaper' or 'a4paper'). 226 # 227 # 'papersize': 'letterpaper', 228 229 # The font size ('10pt', '11pt' or '12pt'). 230 # 231 # 'pointsize': '10pt', 232 233 # Additional stuff for the LaTeX preamble. 234 # 235 # 'preamble': '', 236 237 # Latex figure (float) alignment 238 # 239 # 'figure_align': 'htbp', 240 } 241 242 # Grouping the document tree into LaTeX files. List of tuples 243 # (source start file, target name, title, 244 # author, documentclass [howto, manual, or own class]). 245 latex_documents = [ 246 (master_doc, 'QEMU.tex', u'QEMU Documentation', 247 u'The QEMU Project Developers', 'manual'), 248 ] 249 250 251 # -- Options for manual page output --------------------------------------- 252 # Individual manual/conf.py can override this to create man pages 253 man_pages = [ 254 ('interop/qemu-ga', 'qemu-ga', 255 'QEMU Guest Agent', 256 ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8), 257 ('interop/qemu-ga-ref', 'qemu-ga-ref', 258 'QEMU Guest Agent Protocol Reference', 259 [], 7), 260 ('interop/qemu-qmp-ref', 'qemu-qmp-ref', 261 'QEMU QMP Reference Manual', 262 [], 7), 263 ('interop/qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref', 264 'QEMU Storage Daemon QMP Reference Manual', 265 [], 7), 266 ('system/qemu-manpage', 'qemu', 267 'QEMU User Documentation', 268 ['Fabrice Bellard'], 1), 269 ('system/qemu-block-drivers', 'qemu-block-drivers', 270 'QEMU block drivers reference', 271 ['Fabrice Bellard and the QEMU Project developers'], 7), 272 ('system/qemu-cpu-models', 'qemu-cpu-models', 273 'QEMU CPU Models', 274 ['The QEMU Project developers'], 7), 275 ('tools/qemu-img', 'qemu-img', 276 'QEMU disk image utility', 277 ['Fabrice Bellard'], 1), 278 ('tools/qemu-nbd', 'qemu-nbd', 279 'QEMU Disk Network Block Device Server', 280 ['Anthony Liguori <anthony@codemonkey.ws>'], 8), 281 ('tools/qemu-pr-helper', 'qemu-pr-helper', 282 'QEMU persistent reservation helper', 283 [], 8), 284 ('tools/qemu-storage-daemon', 'qemu-storage-daemon', 285 'QEMU storage daemon', 286 [], 1), 287 ('tools/qemu-trace-stap', 'qemu-trace-stap', 288 'QEMU SystemTap trace tool', 289 [], 1), 290 ('tools/virtfs-proxy-helper', 'virtfs-proxy-helper', 291 'QEMU 9p virtfs proxy filesystem helper', 292 ['M. Mohan Kumar'], 1), 293 ('tools/virtiofsd', 'virtiofsd', 294 'QEMU virtio-fs shared file system daemon', 295 ['Stefan Hajnoczi <stefanha@redhat.com>', 296 'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1), 297 ] 298 man_make_section_directory = False 299 300 # -- Options for Texinfo output ------------------------------------------- 301 302 # Grouping the document tree into Texinfo files. List of tuples 303 # (source start file, target name, title, author, 304 # dir menu entry, description, category) 305 texinfo_documents = [ 306 (master_doc, 'QEMU', u'QEMU Documentation', 307 author, 'QEMU', 'One line description of project.', 308 'Miscellaneous'), 309 ] 310 311 312 313 # We use paths starting from qemu_docdir here so that you can run 314 # sphinx-build from anywhere and the kerneldoc extension can still 315 # find everything. 316 kerneldoc_bin = ['perl', os.path.join(qemu_docdir, '../scripts/kernel-doc')] 317 kerneldoc_srctree = os.path.join(qemu_docdir, '..') 318 hxtool_srctree = os.path.join(qemu_docdir, '..') 319 qapidoc_srctree = os.path.join(qemu_docdir, '..') 320 dbusdoc_srctree = os.path.join(qemu_docdir, '..') 321 dbus_index_common_prefix = ["org.qemu."]