From nobody Thu Nov 14 07:05:56 2024 Delivered-To: importer@patchew.org Received-SPF: temperror (zoho.com: Error in retrieving data from DNS) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=temperror (zoho.com: Error in retrieving data from DNS) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1551972897963790.296575636359; Thu, 7 Mar 2019 07:34:57 -0800 (PST) Received: from localhost ([127.0.0.1]:53936 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1v2e-00025w-9K for importer@patchew.org; Thu, 07 Mar 2019 10:34:42 -0500 Received: from eggs.gnu.org ([209.51.188.92]:33997) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1utM-0002g9-DY for qemu-devel@nongnu.org; Thu, 07 Mar 2019 10:25:10 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h1utL-0004sC-1N for qemu-devel@nongnu.org; Thu, 07 Mar 2019 10:25:04 -0500 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:34451) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h1utK-0004rO-OD for qemu-devel@nongnu.org; Thu, 07 Mar 2019 10:25:02 -0500 Received: by mail-wr1-x436.google.com with SMTP id f14so17901594wrg.1 for ; Thu, 07 Mar 2019 07:25:02 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d1sm5338345wrs.13.2019.03.07.07.25.00 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 07 Mar 2019 07:25:00 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; bh=IX9qKKzwk61zZjXcvq07eP/w0tNuz575ed5tl/v43lU=; b=REyGfFW508F+MNxmgzDMshzlbzl0tUq8mkqOG905rgGnupcATsVS4HDiDPLzZVAcdS rSgJtE/SWoNHsJpbnqYmyw2wQDncvhT1vSGREO+bmpTlJ9jFzDNOEzOBp5svV8LYpx7i NFjYeYAfy/RUX2sz6DiE83/xe31h9gPJDa97bUW2KXQDG+DrwBTd4s2Zwan54qZnoctz ONtuWUuiusdTzs8dLQAXRDw0JzOhx8UDZCozYi72n/MB7YPJIInbnam9NNtyK94s85+e Tr1fJUGV9vE+2ZkWxpDAFkscverel3bA0q2WxOBaTLH1+MRfa4Xf1n6f33GkAwLnhFh1 umBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=IX9qKKzwk61zZjXcvq07eP/w0tNuz575ed5tl/v43lU=; b=o+J4u7OKZsbUv+SB3S7VReFBBfd3nsb9ya9fj2K/AciJkcOIJdw3S1WM8lItLPLL7n j00E52xCVzrWNs0/pCZojUiw/ASsVCRMawMp62CkwfZPIq+yySbFxp+7u84Mb2YslcIg Xsmdoyjs66cEwExq1RsUBr5C3dZRtmCt0Vq5F4u0eYUs2LSgWpDE60y76jKsor/XpbeF NefPgsBMJFu7DIxMFTg2t4ZUoGPV/D4NYGOP7kA2RXDANgsr50AXkwpxyyEq9hX5Ei9F JYjHdq2vz941kvkipU+wopjXLJFwEPxhS6lvVPHSdtTIfTkbsDBCAYXu24bWJHCBGU25 t5Sg== X-Gm-Message-State: APjAAAW+/1dNFFj62Y22cZBwjto2OBt/0Sr8zq8xx21wKneoVDS8B4MC JZvaJhq32mRgL5xbn23E5l3N/kRk6Jg= X-Google-Smtp-Source: APXvYqxdUVJwK/Kc2iK3PsNoK1EJAz4dxkSKBQUlKSDa3yr37TIoHwbed5lOQwU0VtOJpLixcDSZrQ== X-Received: by 2002:a5d:6ace:: with SMTP id u14mr2256460wrw.240.1551972301395; Thu, 07 Mar 2019 07:25:01 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 7 Mar 2019 15:24:46 +0000 Message-Id: <20190307152450.20340-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190307152450.20340-1-peter.maydell@linaro.org> References: <20190307152450.20340-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::436 Subject: [Qemu-devel] [PULL 08/12] docs: Provide separate conf.py for each manual we want X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) By default Sphinx wants to build a single manual at once. For QEMU, this doesn't suit us, because we want to have separate manuals for "Developer's Guide", "User Manual", and so on, and we don't want to ship the Developer's Guide to end-users. However, we don't want to completely duplicate conf.py for each manual, and we'd like to continue to support "build all docs in one run" for third-party sites like readthedocs.org. Make the top-level conf.py support two usage forms: (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. Provide per-manual conf.py files and top level pages for our first two manuals: * QEMU Developer's Guide (docs/devel) * QEMU System Emulation Management and Interoperability Guide (docs/interop) Reviewed-by: Alex Benn=C3=A9e Signed-off-by: Peter Maydell Acked-by: Aleksandar Markovic Message-id: 20190305172139.32662-9-peter.maydell@linaro.org Message-id: 20190228145624.24885-9-peter.maydell@linaro.org --- docs/conf.py | 37 +++++++++++++++++++++++++++++++------ docs/devel/conf.py | 15 +++++++++++++++ docs/devel/index.rst | 21 +++++++++++++++++++++ docs/index.rst | 9 ++------- docs/interop/conf.py | 15 +++++++++++++++ docs/interop/index.rst | 18 ++++++++++++++++++ 6 files changed, 102 insertions(+), 13 deletions(-) create mode 100644 docs/devel/conf.py create mode 100644 docs/devel/index.rst create mode 100644 docs/interop/conf.py create mode 100644 docs/interop/index.rst diff --git a/docs/conf.py b/docs/conf.py index 56a74e0fcb3..f452e424cfe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,6 +3,20 @@ # 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. # @@ -12,13 +26,22 @@ # All configuration values have a default; values that are commented out # serve to show the default. =20 +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 tr= ee. +try: + qemu_docdir +except NameError: + qemu_docdir =3D os.path.abspath(".") + # If extensions (or modules to document with autodoc) are in another direc= tory, # add these directories to sys.path here. If the directory is relative to = the -# documentation root, use os.path.abspath to make it absolute, like shown = here. +# documentation root, use an absolute path starting from qemu_docdir. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir")) =20 =20 # -- General configuration ------------------------------------------------ @@ -91,8 +114,10 @@ html_theme =3D 'alabaster' # Theme options are theme-specific and customize the look and feel of a th= eme # further. For a list of options available for each theme, see the # documentation. -# -# html_theme_options =3D {} +# We initialize this to empty here, so the per-manual conf.py can just +# add individual key/value entries. +html_theme_options =3D { +} =20 # Add any paths that contain custom static files (such as style sheets) he= re, # relative to this directory. They are copied after the builtin static fil= es, diff --git a/docs/devel/conf.py b/docs/devel/conf.py new file mode 100644 index 00000000000..7441f87e7f5 --- /dev/null +++ b/docs/devel/conf.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'devel' manual. +# +# This includes the top level conf file and then makes any necessary tweak= s. +import sys +import os + +qemu_docdir =3D os.path.abspath("..") +parent_config =3D os.path.join(qemu_docdir, "conf.py") +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) + +# This slightly misuses the 'description', but is the best way to get +# the manual title to appear in the sidebar. +html_theme_options['description'] =3D u'Developer''s Guide' diff --git a/docs/devel/index.rst b/docs/devel/index.rst new file mode 100644 index 00000000000..cd0fa6c9ba2 --- /dev/null +++ b/docs/devel/index.rst @@ -0,0 +1,21 @@ +.. This is the top level page for the 'devel' manual. + + +QEMU Developer's Guide +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This manual documents various parts of the internals of QEMU. +You only need to read it if you are interested in reading or +modifying QEMU's source code. + +Contents: + +.. toctree:: + :maxdepth: 2 + + loads-stores + memory + migration + stable-process + testing + diff --git a/docs/index.rst b/docs/index.rst index 93f82228310..3690955dd1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,11 +10,6 @@ Welcome to QEMU's documentation! :maxdepth: 2 :caption: Contents: =20 + interop/index + devel/index =20 - -Indices and tables -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/interop/conf.py b/docs/interop/conf.py new file mode 100644 index 00000000000..cf3c69d4a7e --- /dev/null +++ b/docs/interop/conf.py @@ -0,0 +1,15 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file for the 'interop' manual. +# +# This includes the top level conf file and then makes any necessary tweak= s. +import sys +import os + +qemu_docdir =3D os.path.abspath("..") +parent_config =3D os.path.join(qemu_docdir, "conf.py") +exec(compile(open(parent_config, "rb").read(), parent_config, 'exec')) + +# This slightly misuses the 'description', but is the best way to get +# the manual title to appear in the sidebar. +html_theme_options['description'] =3D u'System Emulation Management and In= teroperability Guide' diff --git a/docs/interop/index.rst b/docs/interop/index.rst new file mode 100644 index 00000000000..2df977dd529 --- /dev/null +++ b/docs/interop/index.rst @@ -0,0 +1,18 @@ +.. This is the top level page for the 'interop' manual. + + +QEMU System Emulation Management and Interoperability Guide +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +This manual contains documents and specifications that are useful +for making QEMU interoperate with other software. + +Contents: + +.. toctree:: + :maxdepth: 2 + + bitmaps + live-block-operations + pr-helper + --=20 2.20.1