From patchwork Thu Feb 28 14:56:21 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1049576 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.b="s33Kqupm"; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 449G7K40ZCz9s1b for ; Fri, 1 Mar 2019 02:05:01 +1100 (AEDT) Received: from localhost ([127.0.0.1]:39734 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNF5-0001Pe-Gx for incoming@patchwork.ozlabs.org; Thu, 28 Feb 2019 10:04:59 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52238) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7V-0004y0-NR for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7T-0008Aa-N9 for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:09 -0500 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:38144) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7M-0007qt-EX for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:04 -0500 Received: by mail-wr1-x42c.google.com with SMTP id g12so10229540wrm.5 for ; Thu, 28 Feb 2019 06:56:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hcu4m0pryKTkWtamgwIRGgnhlBgoakr1uvVzDHoQjSI=; b=s33Kqupm98RJkfcTl/Yo/bEM4H11WgLWZMsGZ7LzToSB9Wzwqw77gWPVybk7qZvFg7 RCuGTcbSfl4LkvKds0uEHT9Jq1ym4f7NFQVOU30xhQkcMpob19rPfvK3hs4hHibRZzwS gqnknXeszVjuUdB20pu++i9YuYdxKpF8l8tavsEdcjBkTJLoVPIff/4jGi2nDwEU3+ux zel/n7a6UFLitLPwWa6cZANyxmXSsDUEk+vKDG+DJoV5FG6FYrXxFsZ91JS/5ylyqLPv uogUBhk4iARJWS9QDDjbdu/z8EarbZRJjxWl+ZlD9jSzqagc0iMRTeEY/l5yZSpb2z+/ LtYA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hcu4m0pryKTkWtamgwIRGgnhlBgoakr1uvVzDHoQjSI=; b=kA+C9IOXyWFj+UMTSnnvBuxyG8ZHplQzhkqehcLCDfYm7RY1gTuZw02VTD0m17MmXK yFjSDh3pAt7xZETJOmLoGPkMtL06++RJdrl/W6SAfsbgDckzVZmVIa5Xl0toyJTfDK2S MWBdU7TfaM8L2n6NZ8FDnkqj4Az+S4592Rva7FIuxez+Vv2GHDv7+JmMJmpcdR3wE0/+ ad8DysCmx8nfczmv4oplh+hBLI6t2sC8VLEWHaaZNJPQteSF2gS+vOY9y8c8HA+hiUW4 FRGBwwiLi28kHKIBO+N/+K4IDpk29kKearPHv+u+aLZDREU3oWO7/+LMVacXpMCfhjpj d8MA== X-Gm-Message-State: APjAAAXzyyoFVVZ1fuFnui7SzsJQhYF6saHpzh3oJ76cuVketKAHwnau nGIwlHN1cpUIO2TjwvecaeyCWzo6guA= X-Google-Smtp-Source: APXvYqxlJ1Muq2noMq3m7bds1lopnpHtjD4QhJ2TdUNwgJCl3Pryo22s+kg617o3kJd5EuXd9La1FA== X-Received: by 2002:adf:ec10:: with SMTP id x16mr6742648wrn.171.1551365809871; Thu, 28 Feb 2019 06:56:49 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.46 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:49 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Thu, 28 Feb 2019 14:56:21 +0000 Message-Id: <20190228145624.24885-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-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::42c Subject: [Qemu-devel] [PATCH v2 08/11] 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: , Cc: patches@linaro.org, =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?utf-8?q?Marc-Andr=C3=A9_Lure?= =?utf-8?q?au?= , Paolo Bonzini , =?utf-8?q?Alex_Benn=C3=A9e?= Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.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 --- 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 c04000e78e4..6a334f545ec 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 ------------------------------------------------ @@ -90,8 +113,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 +