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