From patchwork Thu Mar 7 15:24:46 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 159866 Delivered-To: patch@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp7570433jad; Thu, 7 Mar 2019 07:32:55 -0800 (PST) X-Google-Smtp-Source: APXvYqwMFCbAu2LM8arowl8IG2DPaUCl9qOrM7T9aSDVyAmU2+Y7pyhKZjDGIy0iPY4DXT/2NIvv X-Received: by 2002:a25:4007:: with SMTP id n7mr11852081yba.12.1551972775855; Thu, 07 Mar 2019 07:32:55 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1551972775; cv=none; d=google.com; s=arc-20160816; b=lKrZlVKWUqeOsYn/HPHO2E91RAfnAJIzjQU3tEzy1ydfvoVzZJHDP/Vp6GSemmMbJf g2hxiz3e8ghDWvYtBoTWoVSHfKXo2qhIl/XapjGnCuKLTb45lLAoov5pJYId11Hqp8IW 6tDAVTFXURjkGkRWq4OVeFLjAR4IXYuvrAaK15Vybj1IiTy+X/uJvroPMXlbMwc3qzBe jhRrcuS+0PRhjQBkB5WzsdToOn/M2w9guNFuYYa0WUTZJ9Kgd80kw49LHIl7zQSYsScK ZSIUWY0427ENrZuGHBj5meJkMB8ywFKAKFkTnsVaKfVeZoL5PT3MOstDmga93JF84w03 tmtQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=IX9qKKzwk61zZjXcvq07eP/w0tNuz575ed5tl/v43lU=; b=fm7AhJqTNa1DZbZ9SU+vcp8J3Som/CkfSa3O9Uxcoyy+e4pBHrKRwQfDB5rh6OdQfc kzUG1In8vsGt7M/lmEX88D21yHsx4UCd8KdGSY8tMPoJCWWll1pCdkJ1y/CbYDK+yPW1 MmpBmhdTeHV7DMsvLOamoUHnO9dJdgsk5QNqkNVHPFlEoFOMfy+srX1iG0znSBaFfEWR ZowdwxY4SJ9ahxttJjbQj/bx35t0ACvsdpjDWzuYSFf828WMJS/zCM3GPz/J6kzmQXPB y6CSVHwqu5FiR5SLmRf6sMuQk5rdHu7YnYiWc4nS5BXzAWlE+RXfv0PpkrHN6jm6RrT6 n+nQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=REyGfFW5; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id h144si2802322ywa.384.2019.03.07.07.32.55 for (version=TLS1 cipher=AES128-SHA bits=128/128); Thu, 07 Mar 2019 07:32:55 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=REyGfFW5; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:53892 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1v0x-0000v5-7J for patch@linaro.org; Thu, 07 Mar 2019 10:32:55 -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) 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-Received: by 2002:a5d:6ace:: with SMTP id u14mr2256460wrw.240.1551972301395; Thu, 07 Mar 2019 07:25:01 -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) 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 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+patch=linaro.org@nongnu.org Sender: "Qemu-devel" 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ée 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 -- 2.20.1 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. +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 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")) # -- General configuration ------------------------------------------------ @@ -91,8 +114,10 @@ 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. -# -# html_theme_options = {} +# 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, 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 tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = 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'] = 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 +====================== + +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: + interop/index + devel/index - -Indices and tables -================== - -* :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 tweaks. +import sys +import os + +qemu_docdir = os.path.abspath("..") +parent_config = 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'] = u'System Emulation Management and Interoperability 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 +=========================================================== + +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 +