import os
import sys
import sphinx
+from distutils.version import LooseVersion
from sphinx.errors import ConfigError
-# 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.
-# In newer versions of Sphinx this will display nicely; in older versions
-# Sphinx will also produce a Python backtrace but at least the information
-# gets printed...
-if sys.version_info < (3,6):
- raise ConfigError(
- "QEMU requires a Sphinx that uses Python 3.6 or better\n")
-
# 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.
# This is always the absolute path of the docs/ directory in the source tree.
# ones.
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'2020, 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',
- 'editpage.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.
('tools/virtfs-proxy-helper', 'virtfs-proxy-helper',
'QEMU 9p virtfs proxy filesystem helper',
['M. Mohan Kumar'], 1),
- ('tools/virtiofsd', 'virtiofsd',
- 'QEMU virtio-fs shared file system daemon',
- ['Stefan Hajnoczi <stefanha@redhat.com>',
- 'Masayoshi Mizuma <m.mizuma@jp.fujitsu.com>'], 1),
]
-
-# -- 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_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
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."]
projects / mirror_qemu.git / blobdiff