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 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. 35 try: 36 qemu_docdir 37 except 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 # 44 sys.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. 52 needs_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. 57 extensions = ['kerneldoc', 'qmp_lexer', 'hxtool'] 58 59 # Add any paths that contain templates here, relative to this directory. 60 templates_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'] 66 source_suffix = '.rst' 67 68 # The master toctree document. 69 master_doc = 'index' 70 71 # General information about the project. 72 project = u'QEMU' 73 copyright = u'2019, The QEMU Project Developers' 74 author = 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. 84 try: 85 extracted_version = None 86 with open(os.path.join(qemu_docdir, '../VERSION')) as f: 87 extracted_version = f.readline().strip() 88 except: 89 pass 90 finally: 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. 101 language = 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 106 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 107 108 # The name of the Pygments (syntax highlighting) style to use. 109 pygments_style = 'sphinx' 110 111 # If true, `todo` and `todoList` produce output, else they produce nothing. 112 todo_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. 116 suppress_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. 123 confdir = os.getenv('CONFDIR', "/etc/qemu") 124 rst_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 # 131 html_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. 138 html_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 155 html_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. 165 html_copy_source = False 166 167 # -- Options for HTMLHelp output ------------------------------------------ 168 169 # Output file base name for HTML help builder. 170 htmlhelp_basename = 'QEMUdoc' 171 172 173 # -- Options for LaTeX output --------------------------------------------- 174 175 latex_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]). 196 latex_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 204 man_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) 211 texinfo_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. 222 kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc') 223 kerneldoc_srctree = os.path.join(qemu_docdir, '..') 224 hxtool_srctree = os.path.join(qemu_docdir, '..') 225