aboutsummaryrefslogtreecommitdiff
path: root/docs/conf.py
diff options
context:
space:
mode:
Diffstat (limited to 'docs/conf.py')
-rw-r--r--docs/conf.py78
1 files changed, 67 insertions, 11 deletions
diff --git a/docs/conf.py b/docs/conf.py
index aae0304..f892a6e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,15 +53,21 @@ sys.path.insert(0, os.path.join(qemu_docdir, "../scripts"))
# If your documentation needs a minimal Sphinx version, state it here.
#
-# 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'
+# 3.4.3 is the oldest version of Sphinx that ships on a platform we
+# pledge build support for.
+needs_sphinx = '3.4.3'
# 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', 'depfile', 'qapidoc']
+extensions = [
+ 'depfile',
+ 'hxtool',
+ 'kerneldoc',
+ 'qapi_domain',
+ 'qapidoc',
+ 'qmp_lexer',
+]
if sphinx.version_info[:3] > (4, 0, 0):
tags.add('sphinx4')
@@ -88,7 +94,7 @@ default_role = 'any'
# General information about the project.
project = u'QEMU'
-copyright = u'2024, The QEMU Project Developers'
+copyright = u'2025, The QEMU Project Developers'
author = u'The QEMU Project Developers'
# The version info for the project you're documenting, acts as replacement for
@@ -111,6 +117,32 @@ finally:
else:
version = release = "unknown version"
+bits = version.split(".")
+
+major = int(bits[0])
+minor = int(bits[1])
+micro = int(bits[2])
+
+# Check for a dev snapshot, so we can adjust to next
+# predicted release version.
+#
+# This assumes we do 3 releases per year, so must bump
+# major if minor == 2
+if micro >= 50:
+ micro = 0
+ if minor == 2:
+ major += 1
+ minor = 0
+ else:
+ minor += 1
+
+# These thresholds must match the constants
+# MACHINE_VER_DELETION_MAJOR & MACHINE_VER_DEPRECATION_MAJOR
+# defined in include/hw/boards.h and the introductory text in
+# docs/about/deprecated.rst
+ver_machine_deprecation_version = "%d.%d.0" % (major - 3, minor)
+ver_machine_deletion_version = "%d.%d.0" % (major - 6, minor)
+
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
@@ -139,7 +171,18 @@ suppress_warnings = ["ref.option"]
# environment variable is not set is for the benefit of readthedocs
# style document building; our Makefile always sets the variable.
confdir = os.getenv('CONFDIR', "/etc/qemu")
-rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
+
+vars = {
+ "CONFDIR": confdir,
+ "VER_MACHINE_DEPRECATION_VERSION": ver_machine_deprecation_version,
+ "VER_MACHINE_DELETION_VERSION": ver_machine_deletion_version,
+}
+
+rst_epilog = "".join([
+ ".. |" + key + "| replace:: ``" + vars[key] + "``\n"
+ for key in vars.keys()
+])
+
# We slurp in the defs.rst.inc and literally include it into rst_epilog,
# because Sphinx's include:: directive doesn't work with absolute paths
# and there isn't any one single relative path that will work for all
@@ -147,6 +190,22 @@ rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
with open(os.path.join(qemu_docdir, 'defs.rst.inc')) as f:
rst_epilog += f.read()
+
+# Normally, the QAPI domain is picky about what field lists you use to
+# describe a QAPI entity. If you'd like to use arbitrary additional
+# fields in source documentation, add them here.
+qapi_allowed_fields = {
+ "see also",
+}
+
+# Due to a limitation in Sphinx, we need to know which indices to
+# generate in advance. Adding a namespace here allows that generation.
+qapi_namespaces = {
+ "QGA",
+ "QMP",
+ "QSD",
+}
+
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -187,7 +246,7 @@ html_js_files = [
]
html_context = {
- "display_gitlab": True,
+ "source_url_prefix": "https://gitlab.com/qemu-project/qemu/-/blob/master/docs/",
"gitlab_user": "qemu-project",
"gitlab_repo": "qemu",
"gitlab_version": "master",
@@ -276,9 +335,6 @@ man_pages = [
('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