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