Merge remote-tracking branch 'remotes/pmaydell/tags/pull-sphinx-20190307' into staging (21afe115) · Commits · SUMMER2020 / students / proj-2021291

.gitignore

+1 −0

Original line number	Diff line number	Diff line
		/.doctrees
		/config-devices.*
		/config-all-devices.*
		/config-all-disas.*

MAINTAINERS

+6 −0

Original line number	Diff line number	Diff line
		@@ -2567,3 +2567,9 @@ GIT submodules
		M: Daniel P. Berrange <berrange@redhat.com>
		S: Odd Fixes
		F: scripts/git-submodule.sh

		Sphinx documentation configuration and build machinery
		M: Peter Maydell <peter.maydell@linaro.org>
		S: Maintained
		F: docs/conf.py
		F: docs/*/conf.py

Makefile

+58 −20

Original line number	Diff line number	Diff line
		@@ -87,6 +87,20 @@ endif

		include $(SRC_PATH)/rules.mak

		# Create QEMU_PKGVERSION and FULL_VERSION strings
		# If PKGVERSION is set, use that; otherwise get version and -dirty status from git
		QEMU_PKGVERSION := $(if $(PKGVERSION),$(PKGVERSION),$(shell \
		cd $(SRC_PATH); \
		if test -e .git; then \
		git describe --match 'v*' 2>/dev/null \| tr -d '\n'; \
		if ! git diff-index --quiet HEAD &>/dev/null; then \
		echo "-dirty"; \
		fi; \
		fi))

		# Either "version (pkgversion)", or just "version" if pkgversion not set
		FULL_VERSION := $(if $(QEMU_PKGVERSION),$(VERSION) ($(QEMU_PKGVERSION)),$(VERSION))

		GENERATED_FILES = qemu-version.h config-host.h qemu-options.def

		GENERATED_QAPI_FILES = qapi/qapi-builtin-types.h qapi/qapi-builtin-types.c
		@@ -388,27 +402,12 @@ dummy := $(call unnest-vars,, \

		include $(SRC_PATH)/tests/Makefile.include

		all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
		all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules

		qemu-version.h: FORCE
		$(call quiet-command, \
		(cd $(SRC_PATH); \
		if test -n "$(PKGVERSION)"; then \
		pkgvers="$(PKGVERSION)"; \
		else \
		if test -d .git; then \
		pkgvers=$$(git describe --match 'v*' 2>/dev/null \| tr -d '\n');\
		if ! git diff-index --quiet HEAD &>/dev/null; then \
		pkgvers="$${pkgvers}-dirty"; \
		fi; \
		fi; \
		fi; \
		printf "#define QEMU_PKGVERSION \"$${pkgvers}\"\n"; \
		if test -n "$${pkgvers}"; then \
		printf '#define QEMU_FULL_VERSION QEMU_VERSION " (" QEMU_PKGVERSION ")"\n'; \
		else \
		printf '#define QEMU_FULL_VERSION QEMU_VERSION\n'; \
		fi; \
		(printf '#define QEMU_PKGVERSION "$(QEMU_PKGVERSION)"\n'; \
		printf '#define QEMU_FULL_VERSION "$(FULL_VERSION)"\n'; \
		) > $@.tmp)
		$(call quiet-command, if ! cmp -s $@ $@.tmp; then \
		mv $@.tmp $@; \
		@@ -637,6 +636,14 @@ dist: qemu-$(VERSION).tar.bz2
		qemu-%.tar.bz2:
		$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"

		# Note that these commands assume that there are no HTML files in
		# the docs subdir in the source tree! If there are then this will
		# blow them away for an in-source-tree 'make clean'.
		define clean-manual =
		rm -rf docs/$1/_static
		rm -f docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html
		endef

		distclean: clean
		rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
		rm -f config-all-devices.mak config-all-disas.mak config.status
		@@ -657,6 +664,9 @@ distclean: clean
		rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
		rm -f docs/qemu-block-drivers.7
		rm -f docs/qemu-cpu-models.7
		rm -f .doctrees
		$(call clean-manual,devel)
		$(call clean-manual,interop)
		for d in $(TARGET_DIRS); do \
		rm -rf $$d \|\| exit 1 ; \
		done
		@@ -690,7 +700,18 @@ else
		BLOBS=
		endif

		install-doc: $(DOCS)
		define install-manual =
		for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
		for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
		endef

		# Note that we deliberately do not install the "devel" manual: it is
		# for QEMU developers, and not interesting to our users.
		.PHONY: install-sphinxdocs
		install-sphinxdocs: sphinxdocs
		$(call install-manual,interop)

		install-doc: $(DOCS) install-sphinxdocs
		$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
		$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
		@@ -841,6 +862,23 @@ docs/version.texi: $(SRC_PATH)/VERSION
		%.pdf: %.texi docs/version.texi
		$(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@")

		# Sphinx builds all its documentation at once in one invocation
		# and handles "don't rebuild things unless necessary" itself.
		# The '.doctrees' files are cached information to speed this up.
		.PHONY: sphinxdocs
		sphinxdocs: docs/devel/index.html docs/interop/index.html

		# Canned command to build a single manual
		build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
		# We assume all RST files in the manual's directory are used in it
		manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py

		docs/devel/index.html: $(call manual-deps,devel)
		$(call build-manual,devel)

		docs/interop/index.html: $(call manual-deps,interop)
		$(call build-manual,interop)

		qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
		$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")

		@@ -869,7 +907,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
		docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
		scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi

		html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
		html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
		info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
		pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
		txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt

configure

+13 −2

Original line number	Diff line number	Diff line
		@@ -4589,13 +4589,24 @@ if compile_prog "" "" ; then
		syncfs=yes
		fi

		# Check we have a new enough version of sphinx-build
		has_sphinx_build() {
		# This is a bit awkward but works: create a trivial document and
		# try to run it with our configuration file (which enforces a
		# version requirement). This will fail if either
		# sphinx-build doesn't exist at all or if it is too old.
		mkdir -p "$TMPDIR1/sphinx"
		touch "$TMPDIR1/sphinx/index.rst"
		sphinx-build -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
		}

		# Check if tools are available to build documentation.
		if test "$docs" != "no" ; then
		if has makeinfo && has pod2man; then
		if has makeinfo && has pod2man && has_sphinx_build; then
		docs=yes
		else
		if test "$docs" = "yes" ; then
		feature_not_found "docs" "Install texinfo and Perl/perl-podlators"
		feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"
		fi
		docs=no
		fi

docs/conf.py

0 → 100644

+216 −0

Original line number	Diff line number	Diff line
		# -- coding: utf-8 --
		#
		# QEMU documentation build configuration file, created by
		# sphinx-quickstart on Thu Jan 31 16:40:14 2019.
		#
		# This config file can be used in one of two ways:
		# (1) as a common config file which is included by the conf.py
		# for each of QEMU's manuals: in this case sphinx-build is run multiple
		# times, once per subdirectory.
		# (2) as a top level conf file which will result in building all
		# the manuals into a single document: in this case sphinx-build is
		# run once, on the top-level docs directory.
		#
		# QEMU's makefiles take option (1), which allows us to install
		# only the ones the user cares about (in particular we don't want
		# to ship the 'devel' manual to end-users).
		# Third-party sites such as readthedocs.org will take option (2).
		#
		#
		# This file is execfile()d with the current directory set to its
		# containing dir.
		#
		# Note that not all possible configuration values are present in this
		# autogenerated file.
		#
		# All configuration values have a default; values that are commented out
		# serve to show the default.

		import os
		import sys

		# 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.
		try:
		qemu_docdir
		except NameError:
		qemu_docdir = os.path.abspath(".")

		# If extensions (or modules to document with autodoc) are in another directory,
		# add these directories to sys.path here. If the directory is relative to the
		# documentation root, use an absolute path starting from qemu_docdir.
		#
		# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir"))


		# -- 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'

		# Add any Sphinx extension module names here, as strings. They can be
		# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
		# ones.
		extensions = []

		# Add any paths that contain templates here, relative to this directory.
		templates_path = ['_templates']

		# The suffix(es) of source filenames.
		# You can specify multiple suffix as a list of string:
		#
		# source_suffix = ['.rst', '.md']
		source_suffix = '.rst'

		# The master toctree document.
		master_doc = 'index'

		# General information about the project.
		project = u'QEMU'
		copyright = u'2019, The QEMU Project Developers'
		author = u'The QEMU Project Developers'

		# The version info for the project you're documenting, acts as replacement for
		# \|version\| and \|release\|, also used in various other places throughout the
		# built documents.

		# Extract this information from the VERSION file, for the benefit of
		# standalone Sphinx runs as used by readthedocs.org. Builds run from
		# the Makefile will pass version and release on the sphinx-build
		# command line, which override this.
		try:
		extracted_version = None
		with open(os.path.join(qemu_docdir, '../VERSION')) as f:
		extracted_version = f.readline().strip()
		except:
		pass
		finally:
		if extracted_version:
		version = release = extracted_version
		else:
		version = release = "unknown version"

		# The language for content autogenerated by Sphinx. Refer to documentation
		# for a list of supported languages.
		#
		# 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

		# List of patterns, relative to source directory, that match files and
		# directories to ignore when looking for source files.
		# This patterns also effect to html_static_path and html_extra_path
		exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

		# The name of the Pygments (syntax highlighting) style to use.
		pygments_style = 'sphinx'

		# If true, `todo` and `todoList` produce output, else they produce nothing.
		todo_include_todos = False

		# Sphinx defaults to warning about use of :option: for options not defined
		# with "option::" in the document being processed. Turn that off.
		suppress_warnings = ["ref.option"]

		# -- Options for HTML output ----------------------------------------------

		# The theme to use for HTML and HTML Help pages. See the documentation for
		# a list of builtin themes.
		#
		html_theme = 'alabaster'

		# 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 = {
		}

		# 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']

		# 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',
		]
		}

		# Don't copy the rST source files to the HTML output directory,
		# and don't put links to the sources into the output HTML.
		html_copy_source = False

		# -- Options for HTMLHelp output ------------------------------------------

		# Output file base name for HTML help builder.
		htmlhelp_basename = 'QEMUdoc'


		# -- Options for LaTeX output ---------------------------------------------

		latex_elements = {
		# The paper size ('letterpaper' or 'a4paper').
		#
		# 'papersize': 'letterpaper',

		# The font size ('10pt', '11pt' or '12pt').
		#
		# 'pointsize': '10pt',

		# Additional stuff for the LaTeX preamble.
		#
		# 'preamble': '',

		# Latex figure (float) alignment
		#
		# 'figure_align': 'htbp',
		}

		# Grouping the document tree into LaTeX files. List of tuples
		# (source start file, target name, title,
		# author, documentclass [howto, manual, or own class]).
		latex_documents = [
		(master_doc, 'QEMU.tex', u'QEMU Documentation',
		u'The QEMU Project Developers', 'manual'),
		]


		# -- Options for manual page output ---------------------------------------

		# One entry per manual page. List of tuples
		# (source start file, name, description, authors, manual section).
		man_pages = [
		(master_doc, 'qemu', u'QEMU Documentation',
		[author], 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'),
		]