From patchwork Tue Mar 5 17:21:35 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 10839763 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 4E8CB139A for ; Tue, 5 Mar 2019 17:32:28 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 36FE52CCB5 for ; Tue, 5 Mar 2019 17:32:28 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 2A7FC2CCED; Tue, 5 Mar 2019 17:32:28 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.7 required=2.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 5E3B82CCD3 for ; Tue, 5 Mar 2019 17:32:27 +0000 (UTC) Received: from localhost ([127.0.0.1]:46625 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1DvW-0001iI-MG for patchwork-qemu-devel@patchwork.kernel.org; Tue, 05 Mar 2019 12:32:26 -0500 Received: from eggs.gnu.org ([209.51.188.92]:35637) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1DlL-0002Ee-U2 for qemu-devel@nongnu.org; Tue, 05 Mar 2019 12:21:57 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h1DlK-00016b-Ch for qemu-devel@nongnu.org; Tue, 05 Mar 2019 12:21:55 -0500 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]:39099) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h1DlK-00014W-2U for qemu-devel@nongnu.org; Tue, 05 Mar 2019 12:21:54 -0500 Received: by mail-wr1-x433.google.com with SMTP id l5so10353145wrw.6 for ; Tue, 05 Mar 2019 09:21:53 -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=01uFVxLCrTIEn1+vZ/yUlBMIWfpbKqcloDaOhKzxQNk=; b=TEgUxys19iWKADB6SixsFnaQGKgcRQRybcCEAnrLMkXzsSYkcNeL0Ykoe11Zz574J5 d9ptni9L9TM9rnaM7Y/oIHGfgoprNgiCnKPFLKeCM4xMc7kRXC5/8C643UjX2tsuO41L iZh/i71+MH9P0KhUQxGp39hPw+95TVlpfoo6sOHvRm4YDdkre6hdZACRaMDKnfxMA6Yu ZFyEQ3s64sDKbOEI4yKkCP7VcGa6MT7DfX8PALDyFcj9oXdemy5ccbRsdZwkUw2L/Om7 EmM6/tRd1jy0uccAS4KKbUYzhBiiP1hMDQerHBcjgm9kG9yjhaH+EgT+xN0zqjTBfMKp pzdg== 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=01uFVxLCrTIEn1+vZ/yUlBMIWfpbKqcloDaOhKzxQNk=; b=LQOGBXrzGzJeTQuwUswJDUZqGX25m42ZFppdPVlYsNqSrOhyjN/rkQXwKPG1a/q2pI cdjC1Laz+CdavKzehxbkUfKpjk6nZGkL5v3iSn5lXjfJghc2Xeq73WM6VYkvKaXrPo48 3udfYscgLcoucVzIpvCzvGDIqC1yhEELz9XBv1W5DJZ/W4AVGXuO4bxvsqJ4JujpTAaX RbQVh1KGfBG+YsKF3/gsQkev49KJKP2ikpwtj1pbQBAU2L6jA+OBmfajg1l4wNExGZ56 qKSAZX1Pn6dsL0QirlZE1G4CY20dB0M/d5slc5Ly49x0rTGhLopRp5SieEnHVw8dhxlp OsSw== X-Gm-Message-State: APjAAAUO2D4WVwg6BDpLllBsQWZAdb5Iw2Q2eotqKrh8m+j1FiZ10VFo Jgz/poFhP9IGPcq7kLTm4WVy/wIF2nA= X-Google-Smtp-Source: APXvYqxVDlq/fkk5i8wTpM8zQqSx96hUf1H+ZLi7owwHlM5Z+pph21Ip8KF4Lv24Ygdx/GUNKxIBYA== X-Received: by 2002:a5d:6592:: with SMTP id q18mr16464766wru.230.1551806512564; Tue, 05 Mar 2019 09:21:52 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b195sm48289wmg.36.2019.03.05.09.21.51 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 05 Mar 2019 09:21:51 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 5 Mar 2019 17:21:35 +0000 Message-Id: <20190305172139.32662-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190305172139.32662-1-peter.maydell@linaro.org> References: <20190305172139.32662-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::433 Subject: [Qemu-devel] [PATCH v3 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: , Cc: =?utf-8?q?Alex_Benn=C3=A9e?= , =?utf-8?q?Philipp?= =?utf-8?q?e_Mathieu-Daud=C3=A9?= , Aleksandar Markovic Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP 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: 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. +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 +