import os
import sys
import sphinx
-from sphinx.errors import VersionRequirementError
-
-# Make Sphinx fail cleanly if using an old Python, rather than obscurely
-# failing because some code in one of our extensions doesn't work there.
-# Unfortunately this doesn't display very neatly (there's an unavoidable
-# Python backtrace) but at least the information gets printed...
-if sys.version_info < (3,5):
- raise VersionRequirementError(
- "QEMU requires a Sphinx that uses Python 3.5 or better\n")
+from distutils.version import LooseVersion
+from sphinx.errors import ConfigError
# The per-manual conf.py will set qemu_docdir for a single-manual build;
# otherwise set it here if this is an entire-manual-set build.
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use an absolute path starting from qemu_docdir.
#
+# Our extensions are in docs/sphinx; the qapidoc extension requires
+# the QAPI modules from scripts/.
sys.path.insert(0, os.path.join(qemu_docdir, "sphinx"))
+sys.path.insert(0, os.path.join(qemu_docdir, "../scripts"))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
-# 1.3 is where the 'alabaster' theme was shipped with Sphinx.
-needs_sphinx = '1.3'
+# Sphinx 1.5 and earlier can't build our docs because they are too
+# picky about the syntax of the argument to the option:: directive
+# (see Sphinx bugs #646, #3366).
+needs_sphinx = '1.6'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'qmp_lexer', 'hxtool']
+extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc']
+
+if sphinx.version_info[:3] > (4, 0, 0):
+ tags.add('sphinx4')
+ extensions += ['dbusdoc']
+else:
+ extensions += ['fakedbusdoc']
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = [os.path.join(qemu_docdir, '_templates')]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# The master toctree document.
master_doc = 'index'
+# Interpret `single-backticks` to be a cross-reference to any kind of
+# referenceable object. Unresolvable or ambiguous references will emit a
+# warning at build time.
+default_role = 'any'
+
# General information about the project.
project = u'QEMU'
-copyright = u'2019, The QEMU Project Developers'
+copyright = u'2023, The QEMU Project Developers'
author = u'The QEMU Project Developers'
# The version info for the project you're documenting, acts as replacement for
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'alabaster'
+try:
+ import sphinx_rtd_theme
+except ImportError:
+ raise ConfigError(
+ 'The Sphinx \'sphinx_rtd_theme\' HTML theme was not found.\n'
+ )
+
+html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-# We initialize this to empty here, so the per-manual conf.py can just
-# add individual key/value entries.
-html_theme_options = {
-}
+if LooseVersion(sphinx_rtd_theme.__version__) >= LooseVersion("0.4.3"):
+ html_theme_options = {
+ "style_nav_header_background": "#802400",
+ "navigation_with_keys": True,
+ }
+
+html_logo = os.path.join(qemu_docdir, "../ui/icons/qemu_128x128.png")
+
+html_favicon = os.path.join(qemu_docdir, "../ui/icons/qemu_32x32.png")
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-# QEMU doesn't yet have any static files, so comment this out so we don't
-# get a warning about a missing directory.
-# If we do ever add this then it would probably be better to call the
-# subdirectory sphinx_static, as the Linux kernel does.
-# html_static_path = ['_static']
+html_static_path = [os.path.join(qemu_docdir, "sphinx-static")]
+
+html_css_files = [
+ 'theme_overrides.css',
+]
+
+html_js_files = [
+ 'custom.js',
+]
+
+html_context = {
+ "display_gitlab": True,
+ "gitlab_user": "qemu-project",
+ "gitlab_repo": "qemu",
+ "gitlab_version": "master",
+ "conf_py_path": "/docs/", # Path in the checkout to the docs root
+}
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
-#
-# This is required for the alabaster theme
-# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
-html_sidebars = {
- '**': [
- 'about.html',
- 'navigation.html',
- 'searchbox.html',
- ]
-}
+#html_sidebars = {}
# Don't copy the rST source files to the HTML output directory,
# and don't put links to the sources into the output HTML.
# -- Options for manual page output ---------------------------------------
# Individual manual/conf.py can override this to create man pages
-man_pages = []
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-# dir menu entry, description, category)
-texinfo_documents = [
- (master_doc, 'QEMU', u'QEMU Documentation',
- author, 'QEMU', 'One line description of project.',
- 'Miscellaneous'),
+man_pages = [
+ ('interop/qemu-ga', 'qemu-ga',
+ 'QEMU Guest Agent',
+ ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
+ ('interop/qemu-ga-ref', 'qemu-ga-ref',
+ 'QEMU Guest Agent Protocol Reference',
+ [], 7),
+ ('interop/qemu-qmp-ref', 'qemu-qmp-ref',
+ 'QEMU QMP Reference Manual',
+ [], 7),
+ ('interop/qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref',
+ 'QEMU Storage Daemon QMP Reference Manual',
+ [], 7),
+ ('system/qemu-manpage', 'qemu',
+ 'QEMU User Documentation',
+ ['Fabrice Bellard'], 1),
+ ('system/qemu-block-drivers', 'qemu-block-drivers',
+ 'QEMU block drivers reference',
+ ['Fabrice Bellard and the QEMU Project developers'], 7),
+ ('system/qemu-cpu-models', 'qemu-cpu-models',
+ 'QEMU CPU Models',
+ ['The QEMU Project developers'], 7),
+ ('tools/qemu-img', 'qemu-img',
+ 'QEMU disk image utility',
+ ['Fabrice Bellard'], 1),
+ ('tools/qemu-nbd', 'qemu-nbd',
+ 'QEMU Disk Network Block Device Server',
+ ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
+ ('tools/qemu-pr-helper', 'qemu-pr-helper',
+ 'QEMU persistent reservation helper',
+ [], 8),
+ ('tools/qemu-storage-daemon', 'qemu-storage-daemon',
+ 'QEMU storage daemon',
+ [], 1),
+ ('tools/qemu-trace-stap', 'qemu-trace-stap',
+ 'QEMU SystemTap trace tool',
+ [], 1),
+ ('tools/virtfs-proxy-helper', 'virtfs-proxy-helper',
+ 'QEMU 9p virtfs proxy filesystem helper',
+ ['M. Mohan Kumar'], 1),
]
-
-
+man_make_section_directory = False
# We use paths starting from qemu_docdir here so that you can run
# sphinx-build from anywhere and the kerneldoc extension can still
# find everything.
-kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc')
+kerneldoc_bin = ['perl', os.path.join(qemu_docdir, '../scripts/kernel-doc')]
kerneldoc_srctree = os.path.join(qemu_docdir, '..')
hxtool_srctree = os.path.join(qemu_docdir, '..')
+qapidoc_srctree = os.path.join(qemu_docdir, '..')
+dbusdoc_srctree = os.path.join(qemu_docdir, '..')
+dbus_index_common_prefix = ["org.qemu."]