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