From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549032755961971.5942421483965; Fri, 1 Feb 2019 06:52:35 -0800 (PST) Received: from localhost ([127.0.0.1]:55899 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaBE-0000mb-GC for importer@patchew.org; Fri, 01 Feb 2019 09:52:32 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38758) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9W-0008Ji-PR for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9V-00044E-RL for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:46 -0500 Received: from mail-wr1-x443.google.com ([2a00:1450:4864:20::443]:46537) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9V-00041I-Kt for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:45 -0500 Received: by mail-wr1-x443.google.com with SMTP id l9so7329157wrt.13 for ; Fri, 01 Feb 2019 06:50:40 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:38 -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=yJ/I8VxqVDaXeAhcIT3pinTsIlP8Gad1oLNEkSfIb6o=; b=J/cVwzTpn2r9OZouoTa/oc8itwSesLlLQTQ6nEFZeGr3RPPc2zwLWuzgTi/G8jgjs4 Hv2h+k+eRDWR7bw+t3IdUrcJpJEwDnM1ZDuow63EVCwgpb9oTtDkBhDtGSG8OiOLnz6K OHvD6T8YeyeTJgooOnB/w4c8G4vdbGowKdQas= 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=yJ/I8VxqVDaXeAhcIT3pinTsIlP8Gad1oLNEkSfIb6o=; b=KTl6xk49h7FlpJNp8VVlUpc6YURLm+2NSnmsgt8LCOcDtq9uZaYnVlL7g7+6+iiwEF ZUygBdtYV04xuAmj8stBMUbImmOIprOymQQvuGok6KwIJofGzorYPvBRESW7HBxoZsjH ERzqiFsZRskLqRXSuFW9XKkbDIJrQtc35buhDlGOlvdMJpuX1GzQzKMD+fOhI19tIuUW DSd2uGGfKzVIEHu0BBkIBxu3RfhaxQU869TgLbkT2ictMfba3fBPoJyjP2GH9HV+QJ76 RpX1A6gQKZkZNtk7D1NXHT3awQtlDIdi+7nu+ID5YKPH/3zTgc8Avz4jsVpMXR9TL3SX xWsA== X-Gm-Message-State: AJcUukde/55MUhsIPnprK/YTXzRwNBmi/r5L3oHF1CLO4RFuGKxnrpj5 0e98bgVNHGkfL3TQkVlDxK1Ksdxk3j8lRg== X-Google-Smtp-Source: ALg8bN4d8wmvIc2kMsVUO6yg1jq51Maw5WiUZ/0EcAvX+0vP5kNWEOVq8bskMfZ+Q7ZhVFERyiwfdg== X-Received: by 2002:adf:ec50:: with SMTP id w16mr40097927wrn.171.1549032639520; Fri, 01 Feb 2019 06:50:39 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:25 +0000 Message-Id: <20190201145035.22739-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::443 Subject: [Qemu-devel] [PATCH 01/11] docs/cpu-hotplug.rst: Fix rST markup issues 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" sphinx-build complains: docs/cpu-hotplug.rst:67: ERROR: Unexpected indentation. docs/cpu-hotplug.rst:69: ERROR: Unexpected indentation. docs/cpu-hotplug.rst:74: WARNING: Block quote ends without a blank line; un= expected unindent. docs/cpu-hotplug.rst:75: WARNING: Block quote ends without a blank line; un= expected unindent. docs/cpu-hotplug.rst:76: SEVERE: Unexpected section title. } { docs/cpu-hotplug.rst:78: WARNING: Block quote ends without a blank line; un= expected unindent. These are the result of not indicating one of the literal blocks by finishing the preceding paragraph with the "::" marker. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/cpu-hotplug.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cpu-hotplug.rst b/docs/cpu-hotplug.rst index 1c268e00b41..e2d4e893b01 100644 --- a/docs/cpu-hotplug.rst +++ b/docs/cpu-hotplug.rst @@ -60,7 +60,7 @@ vCPU hotplug hot-plugged (no "qom-path" member). From its output in step (3), we can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0, while hot-plugging a CPU into socket 1 requires passing the listed - properties to QMP ``device_add``: + properties to QMP ``device_add``:: =20 (QEMU) device_add id=3Dcpu-2 driver=3DIvyBridge-IBRS-x86_64-cpu sock= et-id=3D1 core-id=3D0 thread-id=3D0 { --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549032765095692.0348651679354; Fri, 1 Feb 2019 06:52:45 -0800 (PST) Received: from localhost ([127.0.0.1]:55903 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaBL-0000pg-Hs for importer@patchew.org; Fri, 01 Feb 2019 09:52:39 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38827) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9Y-0008Jt-FA for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:50 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9W-00044c-2D for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:48 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:46538) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9V-000432-MJ for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:45 -0500 Received: by mail-wr1-x444.google.com with SMTP id l9so7329238wrt.13 for ; Fri, 01 Feb 2019 06:50:42 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.39 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:40 -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=5kL+Fc5FygULaSo3r/YzdydHS5WCkrxFyRXXNr0TIQw=; b=NWyU41GHwVlP6f+P06jCkcvf+FSxU/5b/UU4gzRpX7DdTSB1QtmsQWjnEUwjBdOifW U3csD3+Dg1DcZgWQhwcRyTPaY73Pxhyv9AXbI7zclAfsNo3L+oe2Ago/nyqNlOCnRIOR PP6le0eFfr+cnJyeyfM2Ttd464JZx/jOlogGQ= 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=5kL+Fc5FygULaSo3r/YzdydHS5WCkrxFyRXXNr0TIQw=; b=Adwklslmksr1LLFapPNg27BcQT/2F4XZwkFhGEpTmxlFMxaa8Tti94xk/K3Sn3Zg41 hKw2ulcMcuamS0LuZr+xN1St45ot7VI/w8wieLpczaznla6oBtzI84SAqOraA6k17+Mp uwgGHCvEumESl6auCU6DyFyLqAytyxUftJQgydIAljagF1AHgG9TmzaX1WFmMlGtprYD mm/Dl0N00OEmdSErlO5s7RaGnxa5rxTTFZ+xID9qaK60uG2uUdlcRtFQZMfGU2YZrtPt jwwX3dmefbeDz1RgmjoVIbDpLEe98goOYgQkR09pbVRY1r++YSYsHl+jXDdLwtmTIh3+ n4Qg== X-Gm-Message-State: AHQUAuZ2xwnCs2U403D3KXEbGFo5TQqcWTuN568i9qekuxdQNK8P+DVi BhQkJmMwhcjuIL6j7+Qb4NjYaaa9x8ymVg== X-Google-Smtp-Source: AHgI3IYAxmSk2fVbp9Gj7FPZhXPMUI+qgopqRWNKWqBQ0UOqglgOIYnilQx1N0cLp9oxfKPSTXmG7Q== X-Received: by 2002:a5d:4046:: with SMTP id w6mr18725611wrp.92.1549032641101; Fri, 01 Feb 2019 06:50:41 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:26 +0000 Message-Id: <20190201145035.22739-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::444 Subject: [Qemu-devel] [PATCH 02/11] docs: Convert memory.txt to rst format 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Convert the memory API documentation from plain text to restructured text format. This is a very minimal conversion: all I had to change was to mark up the ASCII art parts as Sphinx expects for 'literal blocks', and fix up the bulleted lists (Sphinx expects no leading space before the bullet, and wants a blank line before after any list). Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/devel/{memory.txt =3D> memory.rst} | 128 ++++++++++++++------------ 1 file changed, 70 insertions(+), 58 deletions(-) rename docs/devel/{memory.txt =3D> memory.rst} (85%) diff --git a/docs/devel/memory.txt b/docs/devel/memory.rst similarity index 85% rename from docs/devel/memory.txt rename to docs/devel/memory.rst index 42577e1d860..b6a4c37ea5e 100644 --- a/docs/devel/memory.txt +++ b/docs/devel/memory.rst @@ -1,19 +1,20 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D The memory API =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The memory API models the memory and I/O buses and controllers of a QEMU machine. It attempts to allow modelling of: =20 - - ordinary RAM - - memory-mapped I/O (MMIO) - - memory controllers that can dynamically reroute physical memory regions - to different destinations +- ordinary RAM +- memory-mapped I/O (MMIO) +- memory controllers that can dynamically reroute physical memory regions + to different destinations =20 The memory model provides support for =20 - - tracking RAM changes by the guest - - setting up coalesced memory for kvm - - setting up ioeventfd regions for kvm +- tracking RAM changes by the guest +- setting up coalesced memory for kvm +- setting up ioeventfd regions for kvm =20 Memory is modelled as an acyclic graph of MemoryRegion objects. Sinks (leaves) are RAM and MMIO regions, while other nodes represent @@ -98,25 +99,30 @@ ROM device memory region types), this host memory needs= to be copied to the destination on migration. These APIs which allocate the host memory for you will also register the memory so it is migrated: - - memory_region_init_ram() - - memory_region_init_rom() - - memory_region_init_rom_device() + +- memory_region_init_ram() +- memory_region_init_rom() +- memory_region_init_rom_device() =20 For most devices and boards this is the correct thing. If you have a special case where you need to manage the migration of the backing memory yourself, you can call the functions: - - memory_region_init_ram_nomigrate() - - memory_region_init_rom_nomigrate() - - memory_region_init_rom_device_nomigrate() + +- memory_region_init_ram_nomigrate() +- memory_region_init_rom_nomigrate() +- memory_region_init_rom_device_nomigrate() + which only initialize the MemoryRegion and leave handling migration to the caller. =20 The functions: - - memory_region_init_resizeable_ram() - - memory_region_init_ram_from_file() - - memory_region_init_ram_from_fd() - - memory_region_init_ram_ptr() - - memory_region_init_ram_device_ptr() + +- memory_region_init_resizeable_ram() +- memory_region_init_ram_from_file() +- memory_region_init_ram_from_fd() +- memory_region_init_ram_ptr() +- memory_region_init_ram_device_ptr() + are for special cases only, and so they do not automatically register the backing memory for migration; the caller must manage migration if necessary. @@ -218,7 +224,7 @@ For example, suppose we have a container A of size 0x80= 00 with two subregions B and C. B is a container mapped at 0x2000, size 0x4000, priority 2; C is an MMIO region mapped at 0x0, size 0x6000, priority 1. B currently has two of its own subregions: D of size 0x1000 at offset 0 and E of size 0x1000 at -offset 0x2000. As a diagram: +offset 0x2000. As a diagram:: =20 0 1000 2000 3000 4000 5000 6000 7000 8000 |------|------|------|------|------|------|------|------| @@ -228,8 +234,9 @@ offset 0x2000. As a diagram: D: [DDDDD] E: [EEEEE] =20 -The regions that will be seen within this address range then are: - [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] +The regions that will be seen within this address range then are:: + + [CCCCCCCCCCCC][DDDDD][CCCCC][EEEEE][CCCCC] =20 Since B has higher priority than C, its subregions appear in the flat map even where they overlap with C. In ranges where B has not mapped anything @@ -237,8 +244,9 @@ C's region appears. =20 If B had provided its own MMIO operations (ie it was not a pure container) then these would be used for any addresses in its range not handled by -D or E, and the result would be: - [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] +D or E, and the result would be:: + + [CCCCCCCCCCCC][DDDDD][BBBBB][EEEEE][BBBBB] =20 Priority values are local to a container, because the priorities of two regions are only compared when they are both children of the same containe= r. @@ -257,6 +265,7 @@ guest accesses an address: =20 - all direct subregions of the root region are matched against the address= , in descending priority order + - if the address lies outside the region offset/size, the subregion is discarded - if the subregion is a leaf (RAM or MMIO), the search terminates, retur= ning @@ -270,36 +279,39 @@ guest accesses an address: address range), then if this is a container with its own MMIO or RAM backing the search terminates, returning the container itself. Otherwi= se we continue with the next subregion in priority order + - if none of the subregions match the address then the search terminates with no match found =20 Example memory map ------------------ =20 -system_memory: container@0-2^48-1 - | - +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) - | - +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffffff= ff) - | - +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) - | (prio 1) - | - +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xfffff= fff) +:: =20 -pci (0-2^32-1) - | - +--- vga-area: container@0xa0000-0xbffff - | | - | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) - | | - | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) - | - +---- vram: ram@0xe1000000-0xe1ffffff - | - +---- vga-mmio: mmio@0xe2000000-0xe200ffff + system_memory: container@0-2^48-1 + | + +---- lomem: alias@0-0xdfffffff ---> #ram (0-0xdfffffff) + | + +---- himem: alias@0x100000000-0x11fffffff ---> #ram (0xe0000000-0xffff= ffff) + | + +---- vga-window: alias@0xa0000-0xbffff ---> #pci (0xa0000-0xbffff) + | (prio 1) + | + +---- pci-hole: alias@0xe0000000-0xffffffff ---> #pci (0xe0000000-0xfff= fffff) =20 -ram: ram@0x00000000-0xffffffff + pci (0-2^32-1) + | + +--- vga-area: container@0xa0000-0xbffff + | | + | +--- alias@0x00000-0x7fff ---> #vram (0x010000-0x017fff) + | | + | +--- alias@0x08000-0xffff ---> #vram (0x020000-0x027fff) + | + +---- vram: ram@0xe1000000-0xe1ffffff + | + +---- vga-mmio: mmio@0xe2000000-0xe200ffff + + ram: ram@0x00000000-0xffffffff =20 This is a (simplified) PC memory map. The 4GB RAM block is mapped into the system address space via two aliases: "lomem" is a 1:1 mapping of the first @@ -336,16 +348,16 @@ rather than completing successfully; those devices ca= n use the In addition various constraints can be supplied to control how these callbacks are called: =20 - - .valid.min_access_size, .valid.max_access_size define the access sizes - (in bytes) which the device accepts; accesses outside this range will - have device and bus specific behaviour (ignored, or machine check) - - .valid.unaligned specifies that the *device being modelled* supports - unaligned accesses; if false, unaligned accesses will invoke the - appropriate bus or CPU specific behaviour. - - .impl.min_access_size, .impl.max_access_size define the access sizes - (in bytes) supported by the *implementation*; other access sizes will be - emulated using the ones available. For example a 4-byte write will be - emulated using four 1-byte writes, if .impl.max_access_size =3D 1. - - .impl.unaligned specifies that the *implementation* supports unaligned - accesses; if false, unaligned accesses will be emulated by two aligned - accesses. +- .valid.min_access_size, .valid.max_access_size define the access sizes + (in bytes) which the device accepts; accesses outside this range will + have device and bus specific behaviour (ignored, or machine check) +- .valid.unaligned specifies that the *device being modelled* supports + unaligned accesses; if false, unaligned accesses will invoke the + appropriate bus or CPU specific behaviour. +- .impl.min_access_size, .impl.max_access_size define the access sizes + (in bytes) supported by the *implementation*; other access sizes will be + emulated using the ones available. For example a 4-byte write will be + emulated using four 1-byte writes, if .impl.max_access_size =3D 1. +- .impl.unaligned specifies that the *implementation* supports unaligned + accesses; if false, unaligned accesses will be emulated by two aligned + accesses. --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549033150888439.2678630098377; Fri, 1 Feb 2019 06:59:10 -0800 (PST) Received: from localhost ([127.0.0.1]:56015 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaHd-000665-GT for importer@patchew.org; Fri, 01 Feb 2019 09:59:09 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38807) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9Y-0008Jo-1S for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:50 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9W-00044i-2E for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:47 -0500 Received: from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b]:43781) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9V-00043F-PK for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:45 -0500 Received: by mail-wr1-x42b.google.com with SMTP id b4so473037wrq.10 for ; Fri, 01 Feb 2019 06:50:43 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.41 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:41 -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=6mce9QSSNUlxaAEe6w3PiUziOPnSKM6yCS8EwWRp0C0=; b=ITG+ImdoW1C5reX/SCw2vtTLncoJUo+78Jm62pLZCq5OoklUBsCf9h2fzp9ntRCB1g LnYl5PxpSIwS3rm+eeorUema+f47Cv2FRvtQINqwFTVcuPbyXgVyn8HJ5+UOcXQ/FG+K EJSmEwuihZoik+N9qKoZWzR19c2Qcx8uMXG4o= 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=6mce9QSSNUlxaAEe6w3PiUziOPnSKM6yCS8EwWRp0C0=; b=jhQ3pXzckcOsfKL5ftOyhIn1f4pBDAFJ7CmhVEm/Z6MiPPtyWyUp9t1TgvbZDhKLO0 X/YmXPQE6LDO6pgsDFCg7y9nc85isBJx6GobHAX4kVQWXNXa3t8i8cxxhIMG1tz9i2zX 7JMamyt2XJLm7UE2/a/stKUEzWEaSWrBy2c/k9eDeziodUsagVL2kESqs7/qy5hLh/yF Lp/67a7OlTtExC8+9fzXFcu6BwHjxD0iVtMmbQr+5s8otOE/1Z7xf30IpcugmQECcgeJ M9g0i0kJC5EOSN4/MzKHJpt6xFpuL79pj2wIcRjVO8fOtTRlvNU6gVV32plLJWMDB7Aj P25w== X-Gm-Message-State: AJcUukffWGPa9ZJ12lHoWCJmn4dCdapyYnxHXKNafHez2TwG0kmn4pqk P6tI0V6ABFzp/IwxG4u35qAW9216kFp9hw== X-Google-Smtp-Source: ALg8bN5f5VWFEr/QtpvEzohwQkntH7eMvh4G3Gb1ZwSe98WSrHKdQB+h19sdaLQpx+Smw9VALpsJNQ== X-Received: by 2002:adf:b502:: with SMTP id a2mr41317554wrd.54.1549032642367; Fri, 01 Feb 2019 06:50:42 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:27 +0000 Message-Id: <20190201145035.22739-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::42b Subject: [Qemu-devel] [PATCH 03/11] docs: Commit initial files from sphinx-quickstart 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Commit the initial Sphinx conf.py and skeleton index.rst as generated with sphinx-quickstart Reviewed-by: Alex Benn=C3=A9e --- docs/conf.py | 168 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 20 ++++++ 2 files changed, 188 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000000..53a17506615 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,168 @@ +# -*- coding: utf-8 -*- +# +# QEMU documentation build configuration file, created by +# sphinx-quickstart on Thu Jan 31 16:40:14 2019. +# +# 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. + +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx =3D '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions =3D [] + +# Add any paths that contain templates here, relative to this directory. +templates_path =3D ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix =3D ['.rst', '.md'] +source_suffix =3D '.rst' + +# The master toctree document. +master_doc =3D 'index' + +# General information about the project. +project =3D u'QEMU' +copyright =3D u'2019, The QEMU Project Developers' +author =3D 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. +# +# The short X.Y version. +version =3D u'4.0' +# The full version, including alpha/beta/rc tags. +release =3D u'4.0' + +# 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 =3D 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 =3D ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style =3D 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos =3D False + + +# -- 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 =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 {} + +# 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, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path =3D ['_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#sideba= rs +html_sidebars =3D { + '**': [ + 'relations.html', # needs 'show_related': True theme option to di= splay + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename =3D 'QEMUdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements =3D { + # 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 =3D [ + (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 =3D [ + (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 =3D [ + (master_doc, 'QEMU', u'QEMU Documentation', + author, 'QEMU', 'One line description of project.', + 'Miscellaneous'), +] + + + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000000..93f82228310 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,20 @@ +.. QEMU documentation master file, created by + sphinx-quickstart on Thu Jan 31 16:40:14 2019. + You can adapt this file completely to your liking, but it should at lea= st + contain the root `toctree` directive. + +Welcome to QEMU's documentation! +=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 + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +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` --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549032894698526.7910437907396; Fri, 1 Feb 2019 06:54:54 -0800 (PST) Received: from localhost ([127.0.0.1]:55919 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaDS-0002XF-TO for importer@patchew.org; Fri, 01 Feb 2019 09:54:50 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38761) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9X-0008Jj-1R for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9W-00044R-0X for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:46 -0500 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:46536) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9V-00043j-H1 for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:45 -0500 Received: by mail-wr1-x441.google.com with SMTP id l9so7329374wrt.13 for ; Fri, 01 Feb 2019 06:50:44 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.42 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:43 -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=vVcq4uPvDCVi9HBueMYXg++o0hzqesdl6sfILsn/e8Y=; b=AB68a6oYM155A3CvsxM171Eq4Td3/O6n+o+NHE2NDB6IEaXZRUHSniRi9vL32vGOWH 061JcsOJgbTfv+fcYo7t6Asa6CuoCfvCMThUvWssu9NwZd7E7H59+K7TfPCljZVij72q moRnACk5ENlB6WLSlbNC/gDJe0J8uyi3X89o0= 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=vVcq4uPvDCVi9HBueMYXg++o0hzqesdl6sfILsn/e8Y=; b=nsbPZ5upnXgEnVaBDQ9fzF3BiHYEuGVZqLUAv8L1QRO60xXUmQO3q8WM9FRar0r8+j G70C9W7EdvsXdk0dWrtZB4b7c5T6prhVfhUkGrCw6YTt8ccZ4Q5vV5kY0TuJRn+P4Ncb 6oUOK1U6ifGl1DPLSkls6AGIHKdWFLBVmQC+wszurjRpt6oIpYNf3dPTLTYJNaK15veI aXw6ElKUo58ujwVgrVcV3HYPtx691JLVvGhtDltJCsgfVEhTsYLEaLaUm6dqUNB+6bwE DRr1HxjV0cNgWfidH+B6NIRqJETU13woeQVvpIKPfzhGJSaL1i2qgD/IG8H8Q089kDfd waIA== X-Gm-Message-State: AJcUukeeKTY9TYzHniHj7b6QPn96HTxORCOkPLpZnNXfAUHN1hmVrZdE dLlya8gDpxiyVQbKvdpfGH1prrcNh+rTVQ== X-Google-Smtp-Source: ALg8bN4y8TSXrq8Jk0468CFa6JAkr7+NYWoMuZK4jOFjNThgmYPtcMX3TvS+gQZ3YRYkgDNlpZiJWw== X-Received: by 2002:adf:a14d:: with SMTP id r13mr37349525wrr.169.1549032643914; Fri, 01 Feb 2019 06:50:43 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:28 +0000 Message-Id: <20190201145035.22739-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::441 Subject: [Qemu-devel] [PATCH 04/11] docs/conf.py: Disable unused _static directory 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We don't yet have any custom static files, so disable this config file setting to avoid a warning from sphinx about not being able to find the directory. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 53a17506615..e1d08a34a65 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,7 +93,11 @@ html_theme =3D 'alabaster' # 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, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path =3D ['_static'] +# 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 =3D ['_static'] =20 # Custom sidebar templates, must be a dictionary that maps document names # to template names. --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549033027395185.31652275392287; Fri, 1 Feb 2019 06:57:07 -0800 (PST) Received: from localhost ([127.0.0.1]:55985 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaFd-0004M3-KC for importer@patchew.org; Fri, 01 Feb 2019 09:57:05 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38818) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9Y-0008Js-8Y for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9W-00045U-KX for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:48 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:45906) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9W-00044A-CF for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:46 -0500 Received: by mail-wr1-x444.google.com with SMTP id t6so7330030wrr.12 for ; Fri, 01 Feb 2019 06:50:46 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:44 -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=qdKXnGaIcRR1Ept+AtLXN0B4XgPtrXjB5PKfiWINGPQ=; b=IHtXZ/2rjjXJZUR+DltzEdB3gabXpbsp+j/n7UZlMLE8VVjZ8zSXX2UJIWbJ/ssBWz Kuzfo4PAOH+8lios/xyYR7Hiqx5F2tS+7cw+r/ljbIlarkX/3rSs8E1oAwJlrsyQXTJA Ysn0PA2AceckANb6rFRscrdWfaVqrIvOnswP8= 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=qdKXnGaIcRR1Ept+AtLXN0B4XgPtrXjB5PKfiWINGPQ=; b=Cmhc6YZNbZ81OYhBebhW3N2vkx01PF2HUB5R/SrfB2vvQIt/G9svRq9d7FPxomOqcf q6C9OwjqxYI78hl5fg/swKn26QCFmwDSUH5lu0YxH6TltPXpJyASDHZCt9xH7HGcc8aR HomV5oriRLudhWqHmHyFEnHDIEvs7xdAFoS5H/DGWAlP+w4z0c0NSmf42DHtHum6P3iN wZjAtqPelF6YwqciR8Bye36houVSoNYwPubFN4Y/SDjW4velEWalnPkWzHZit74HFL/X +LNxi1cegZBKCkZVBXUGfDHmFFrg0Y6WG8yIXeXaQbvSfTEbtCg134uboZWBPGLFnJJV UWag== X-Gm-Message-State: AJcUukdT2jzqm1g0U75nUhSrn4rm9hwvTx+OGj9CT05I/V8EnmJCpmKi Bjs19G71DPtle70A3gdiW+tyunsr+2VuPw== X-Google-Smtp-Source: ALg8bN7VXK64pLTKjfTpXl0RV1IWjrldZ5Lq25C+3sQ0MlhMwwE7gsOZDdYaXly/pVkuvAoR35se1w== X-Received: by 2002:adf:8506:: with SMTP id 6mr40531175wrh.128.1549032645214; Fri, 01 Feb 2019 06:50:45 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:29 +0000 Message-Id: <20190201145035.22739-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::444 Subject: [Qemu-devel] [PATCH 05/11] docs/conf.py: Configure the 'alabaster' theme 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Add the 'navigation' bar to the sidebar, which for some reason is not enabled by default. Remove 'relations', which is effectively disabled anyway and isn't useful for us. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index e1d08a34a65..348e6358740 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -106,7 +106,8 @@ html_theme =3D 'alabaster' # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sideba= rs html_sidebars =3D { '**': [ - 'relations.html', # needs 'show_related': True theme option to di= splay + 'about.html', + 'navigation.html', 'searchbox.html', ] } --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549033227368923.5839904588088; Fri, 1 Feb 2019 07:00:27 -0800 (PST) Received: from localhost ([127.0.0.1]:56047 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaIo-0006nM-EH for importer@patchew.org; Fri, 01 Feb 2019 10:00:22 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38846) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9Z-0008K4-EU for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:50 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9X-00047E-Sr for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:49 -0500 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:35884) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9X-00045w-LX for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:47 -0500 Received: by mail-wr1-x444.google.com with SMTP id u4so7399283wrp.3 for ; Fri, 01 Feb 2019 06:50:47 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.45 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:45 -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=ZY0Hoyr2WjIv2JxshJowtprF9j8SAVs74kkDD+37vmY=; b=KpqYbQPhsgJT5ARxYyzF6HfhMDTDRodowZAyEPJvFFLbKChji840FWnQQkNJRp+Jti q6/iv7i6iSm1xfwblwHcPZz4C0Qv1bLKGIUguKDjP7m/LhQQkJVbLCTWwiFi/fa7t4d/ nd2ymBGNJdM2xHSovQg+ppxihCbvq/uCyknko= 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=ZY0Hoyr2WjIv2JxshJowtprF9j8SAVs74kkDD+37vmY=; b=ajcQ0Y3f0ECLh18b9jGSGN4nfxqkHD1vp9sTAT0rfyfuhZxyw+RphmYdZmAtatjlX3 H7ciBZjXIeOsFoFwjYUStrmkTl4t0Tx4gBsqBOWdW7546GoXIx7PzxawtXoi7VmCtk79 /YFqxfsDQDeW/XSW3gdUxQMQkl3oBr1OtdkIhP7lJ43c5X+qSlPSgWz2WJzAI9FX5nzP 0rI7xG2CrOAYgLAMGDW/BKYW7QQnc6dgD4lnb6Sw5c7m3QoWDHlP/7cpHdUpH9pYJ3Uk QJ7cZhGyfWmSTkFpisZPJ6WlGnPfGUlDOOAWUweSDyCZr+/xmlr6lOkf8s23F/k0GerZ L/nA== X-Gm-Message-State: AJcUukdCX/u8x2o6lDU9lGL0RitBSAFTSUK01m8ai5H2zY80YujSsZ9p x5u/bmZzEcR5B5ObeswFAwMDrwSiTzFP5g== X-Google-Smtp-Source: ALg8bN6m0s3we5wVfGYRMz7zjrRJdQT/nhA8K6o06Mg7avRUv/oU1SqdrSGqU+VKBT7XSkw2myzfRg== X-Received: by 2002:a05:6000:104b:: with SMTP id c11mr39612354wrx.303.1549032646446; Fri, 01 Feb 2019 06:50:46 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:30 +0000 Message-Id: <20190201145035.22739-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::444 Subject: [Qemu-devel] [PATCH 06/11] docs/conf.py: Don't include rST sources in HTML build 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Sphinx defaults to including all the rST source files in the HTML build and making each HTML page link to the source file. Disable that. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 348e6358740..6ddaa549f28 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,6 +112,9 @@ html_sidebars =3D { ] } =20 +# 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 =3D False =20 # -- Options for HTMLHelp output ------------------------------------------ =20 --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549032897624423.51859109208965; Fri, 1 Feb 2019 06:54:57 -0800 (PST) Received: from localhost ([127.0.0.1]:55921 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaDW-0002Zd-7M for importer@patchew.org; Fri, 01 Feb 2019 09:54:54 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38876) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9a-0008Kz-Js for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:51 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9Z-00048q-Gi for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:50 -0500 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:39984) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9Z-00047h-6h for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:49 -0500 Received: by mail-wr1-x42f.google.com with SMTP id p4so7372821wrt.7 for ; Fri, 01 Feb 2019 06:50:49 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.46 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:46 -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=8fOtyaNVqoJDUauRkZ23KSyTse3Vfwomv1ji9q1oFiI=; b=LZHcLUbCCGYnMixiXUF6F2T+QHStBnncGpbbtGmrtd/J+0LShbwbXrhRkq772Binnt HM8CeMJ2JQyBdYoJLIgt3hWk4kHLgmoAKoRHm9+ASFdzMrTsHXz2XoV60vsV+iu6VHfJ 604LHnZySW8rIjD5UkSpa/WKQ0uIwDA54Qahk= 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=8fOtyaNVqoJDUauRkZ23KSyTse3Vfwomv1ji9q1oFiI=; b=FamhBI6PTCOE3xYP8fLSeun7npQWdJw2Y0jj3NAjTXKBL5S9bA3DgjDkHos8kIHDMI qrasJ1ANDpduGZVzTnFa3f8/PkACyF93q+hur6PP1BlR8AUEZOjKz4K/NdEIgqsG18mH +w4oaGvjjEV4TcYV9r32KxZrwKkwSbnmfX+X4nWbI//501wnUKyZUIcTj/h5WqjcDzrK efcimtFdEmewN1WoWbHbnH0JINKGQ3FlegJUnAi5Pz9aQATHdbKefjnJi7gAJBt52BRA c8cQ5Lm4pVoJlVdM24wRAqS48ApQkod9P02UcH26Eq0cLPjqPmkbPcZZOH76ksJZAYrL iWVg== X-Gm-Message-State: AHQUAubiaZBz4exXanOgH+pJg00hx2rQG65Ns344XHiIvkrqLymdl7nF hsVIrKOkw1iltTCji+o1BYyyc93bq+Oc4A== X-Google-Smtp-Source: AHgI3IZuiNMrM+ZRqzAUmjMAuvQK26LH7mas+cadCrstKlrIzpfMIFaG4QvMXxOdurPZHe4mMORRuQ== X-Received: by 2002:adf:f6c9:: with SMTP id y9mr1723466wrp.138.1549032647843; Fri, 01 Feb 2019 06:50:47 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:31 +0000 Message-Id: <20190201145035.22739-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::42f Subject: [Qemu-devel] [PATCH 07/11] docs/conf.py: Disable option warnings 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" sphinx-build complains about using :option: to mark up option flags that it doesn't know about (because they were not defined using the "option::" directive): docs/pr-manager.rst:68: WARNING: unknown option: -d Suppress these warnings. This way we get the semantic markup of the option flag but no cross-referencing hyperlink. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- docs/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 6ddaa549f28..c04000e78e4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -76,6 +76,9 @@ pygments_style =3D 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos =3D False =20 +# Sphinx defaults to warning about use of :option: for options not defined +# with "option::" in the document being processed. Turn that off. +suppress_warnings =3D ["ref.option"] =20 # -- Options for HTML output ---------------------------------------------- =20 --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 154903330808538.9237963613358; Fri, 1 Feb 2019 07:01:48 -0800 (PST) Received: from localhost ([127.0.0.1]:56087 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaKA-0007b5-Pm for importer@patchew.org; Fri, 01 Feb 2019 10:01:46 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38888) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9c-0008MN-7N for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9a-0004AG-Ta for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:52 -0500 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:36877) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9a-00049b-LT for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:50 -0500 Received: by mail-wr1-x435.google.com with SMTP id s12so7396945wrt.4 for ; Fri, 01 Feb 2019 06:50:50 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.47 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:48 -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=FKkFoERye0Qk2mAM+PAXMHGxGZKBwpoLIKSbeAC6HpM=; b=inAQnf3jfOFWps/mcVKjhXNC5ohoPPwke3h73/GJp/+qk53khrcH+4HxMmXG5u8u4v nxAMK2beqW1QhhcjWOtVyIbFSquFLGrV/4D9UXzyimPh921ZLutM2NeY3k93WR6/D/w6 rSuheWZMpZhCYeZy80rMbSghvYNLoOAVjkYBY= 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=FKkFoERye0Qk2mAM+PAXMHGxGZKBwpoLIKSbeAC6HpM=; b=T4DGT8RVOyjmz9KOK20mEwJsdDN74LMmanSUD8dz6g18kckQkYRMH+/9flpgPheehh DQFuGkgjvVyCIGj7woBCONcCQ0mOdfBQ+Qa9EdEpVHn+ulkJtsgDL7LDQUhWkR9esGre SGZpiz5lVh44PzrbaPx1Xpd3aK6uukI5J11PiFEXLxifiP/vNVoRQSN3ptQa2KFmXmq0 Qq2Cl7yi00SuSzSPTTP55+SS91vMSlvn0eQL/PqCkq55LV2lY8EqL02xi0BM93XmJUfW ylA1PyQWgy44oEJB+YMbHDuNjLcwviIZsB9BZA3ausACPPBAx9rkVPr6JUqwsSQfDLvc OdgA== X-Gm-Message-State: AJcUukflJrlfXJprryhsGYSyqbx1Vr8r0KjZrkzTMajY0X2oKlneldJn VaA0I9lBi7EuKyrKn8tvz2zwg2+TD5TyUQ== X-Google-Smtp-Source: ALg8bN7ZRzhsoSY+krurd2e092fnBjYC2vQ1TzrQ5NzrHYo4i+LeCafOwSHs3hblr1fWpVld2O8iPA== X-Received: by 2002:adf:b502:: with SMTP id a2mr41317968wrd.54.1549032649250; Fri, 01 Feb 2019 06:50:49 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:32 +0000 Message-Id: <20190201145035.22739-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::435 Subject: [Qemu-devel] [PATCH 08/11] 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Reviewed-by: Alex Benn=C3=A9e --- 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. =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 ------------------------------------------------ @@ -90,8 +113,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 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 15490330306231018.6806551258413; Fri, 1 Feb 2019 06:57:10 -0800 (PST) Received: from localhost ([127.0.0.1]:55989 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaFh-0004O2-6q for importer@patchew.org; Fri, 01 Feb 2019 09:57:09 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38904) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9d-0008NG-BQ for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9c-0004CK-6d for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:53 -0500 Received: from mail-wm1-x342.google.com ([2a00:1450:4864:20::342]:51624) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9c-0004Ap-00 for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:52 -0500 Received: by mail-wm1-x342.google.com with SMTP id b11so6412811wmj.1 for ; Fri, 01 Feb 2019 06:50:51 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.49 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:49 -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=vdwqp6tUu+2j46vNAuDpciGt92Qn8b7MicvO/kAG+Oo=; b=VwogaEyGmiizJ3OLVG35kfJiA+CBgmDDVGvWUKi4IS+UhpNJIc9HczmfUEIchnAx6C 9rGRvWqLqj7c+lLO3bUeVGk60hMjinAt/FeKlgQhFywM67ZVn0nHnSRw1uX6yAXRRetQ 00H30gMsqNTtNYz0bUsmZR2rDqsSkaxK6u8w4= 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=vdwqp6tUu+2j46vNAuDpciGt92Qn8b7MicvO/kAG+Oo=; b=OJJNLzBjpYXohWM0zpCfL+vrY+tvKU38z1jyzhIGLdHd90tucSv9k6IqQystym930U 0HT5MjkKC3F1cFOfmX6sBJcgcVSlQ/p5CUpuJaBmep6+Vl5gIhJ4SrkecGNx/ngK2owV /yF8KWvO2C4rcQ0CoT0iJ83T2oCMg0xXk07/b2lSjAGWvojf924XlBSzyZretHJoSdTb O2lYBqiUbR/UDyB7BUpMcC61E9CAt6l77CpKsQhon6nqh+NvRb8reItS+9+ZdHf7Luct L9uq5I7SNEpBD8Kj01vjQ0cWp68RYR3e7eheu7NJBl5G5URXV1oLNpKG6CYc9MrIscjl 07rA== X-Gm-Message-State: AHQUAuZ4lRdr6xfv04xq0SEHJSecaV1hAnRB09ImJCSbGKVqVAHtmKGh KgO2cUPeXX+/oTBrdHkxqS1VGCmIvOFNeg== X-Google-Smtp-Source: AHgI3Iap+kHa8HcGaDf6VaC54MlooKl+22ypmNNilnsG8zCrAAtalhW5QNonqH6umqN/jKd/0FgcQA== X-Received: by 2002:a1c:f71a:: with SMTP id v26mr2604941wmh.131.1549032650526; Fri, 01 Feb 2019 06:50:50 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:33 +0000 Message-Id: <20190201145035.22739-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::342 Subject: [Qemu-devel] [PATCH 09/11] Makefile, configure: Support building rST documentation 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Add support to our configure and makefile machinery for building our rST docs into HTML files. Building the documentation now requires that sphinx-build is available; this seems better than allowing half the docs to be built if it is not present but having half of them missing. (In particular it means that assuming that distros configured with --enable-docs they'll get a helpful error from configure telling them the new build dependency.) Signed-off-by: Peter Maydell --- configure | 4 ++-- Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) diff --git a/configure b/configure index b18281c61f3..9cd5c0cd0bd 100755 --- a/configure +++ b/configure @@ -4561,11 +4561,11 @@ fi =20 # Check if tools are available to build documentation. if test "$docs" !=3D "no" ; then - if has makeinfo && has pod2man; then + if has makeinfo && has pod2man && has sphinx-build; then docs=3Dyes else if test "$docs" =3D "yes" ; then - feature_not_found "docs" "Install texinfo and Perl/perl-podlators" + feature_not_found "docs" "Install texinfo, Perl/perl-podlators and p= ython-sphinx" fi docs=3Dno fi diff --git a/Makefile b/Makefile index 1278a3eb529..d519fadee39 100644 --- a/Makefile +++ b/Makefile @@ -387,7 +387,7 @@ dummy :=3D $(call unnest-vars,, \ =20 include $(SRC_PATH)/tests/Makefile.include =20 -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules +all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules =20 qemu-version.h: FORCE $(call quiet-command, \ @@ -631,6 +631,14 @@ dist: qemu-$(VERSION).tar.bz2 qemu-%.tar.bz2: $(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2= ,%,$@)" =20 +# 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 =3D +rm -rf docs/$1/_static +rm 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 @@ -651,6 +659,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 @@ -684,7 +695,18 @@ else BLOBS=3D endif =20 -install-doc: $(DOCS) +define install-manual =3D +for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qe= mu_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)" @@ -835,6 +857,23 @@ docs/version.texi: $(SRC_PATH)/VERSION %.pdf: %.texi docs/version.texi $(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@") =20 +# 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 =3D $(call quiet-command,sphinx-build $(if $(V),,-q) -b html = -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 =3D $(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","$@= ") =20 @@ -863,7 +902,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 =20 -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html sphinxdocs info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-re= f.info pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.p= df txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.t= xt --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549032897813121.20367075722766; Fri, 1 Feb 2019 06:54:57 -0800 (PST) Received: from localhost ([127.0.0.1]:55923 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaDY-0002b9-Fe for importer@patchew.org; Fri, 01 Feb 2019 09:54:56 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38914) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9e-0008OF-0P for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9d-0004DO-5U for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:53 -0500 Received: from mail-wm1-x32b.google.com ([2a00:1450:4864:20::32b]:52707) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9c-0004CU-Vt for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:53 -0500 Received: by mail-wm1-x32b.google.com with SMTP id m1so6398611wml.2 for ; Fri, 01 Feb 2019 06:50:52 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.50 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50: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=tg0YYMVzNWa7GJGbDhPTQaivAnAM9h0rP6Nqt+KE/Nk=; b=iKmAIU5LAwVhUvnfmCUxrF60O1+OzMhHK2dWiQePrXFmo0vr04qQTYTyGV6BQ0xdEn ERKST7PAbuHlwDSecl9nHPw6UrIQznpJiEi1NgxQvwQNAGsUltfopBpvhAMjs3CgSHAZ qvlCpkz2pBZ/N6n/AWjhXW7SisyWNw0E0LgiI= 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=tg0YYMVzNWa7GJGbDhPTQaivAnAM9h0rP6Nqt+KE/Nk=; b=sex87LSB/TfgQFGVSusmSF9zdu7zUt0FNFCEgmceXbWghxY6eFkene6wWy1Y7B9w4b 0GyxqqZ0VsWhCk5LK40lZmxTzAZKaYIkriS4bA47FzGB85YNY7yyftPN9F8ye81i02a3 kTrnJ0HY9pi3yBbVmX2EepvACXu6k6lxFgbiR845EwSNY53aWnkz9aFE3Qy8t2o8XAbv w5Ww6F7PGTrSch7UxPTM6tFSVYrQpSmeLAaIZS5h0nNML/48TvlRPwvGX+AVgeIszOL4 8/bH6hmMdWxwXApGAddC4Q/6k01QoI6XFf1FKIm1eL/n360Bwuw+BOHCoK3sC8teKpaW 59Jw== X-Gm-Message-State: AHQUAuau++/TC9xskCcUmSyT9XpJpmP1sZCqi2jhaDt2f4dTkx1G7Aq3 6baRky3xT571kkY0LvkX8tWM8jk9VNvRlQ== X-Google-Smtp-Source: AHgI3IZ+FVmMSpXoFL96f7OWlbPNj1UG5KhVWRKivDKfGI1ldsvWOnWSfveOgjJPxxXes5eh/dr/Nw== X-Received: by 2002:a1c:2804:: with SMTP id o4mr2896368wmo.150.1549032651670; Fri, 01 Feb 2019 06:50:51 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:34 +0000 Message-Id: <20190201145035.22739-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::32b Subject: [Qemu-devel] [PATCH 10/11] Makefile: Abstract out "identify the pkgversion" code 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Abstract out the "identify the pkgversion" code from the rule for creating qemu-version.h, so it sets makefile variables for QEMU_PKGVERSION and QEMU_FULL_VERSION. (We will want to use these when building the Sphinx docs.) Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- Makefile | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/Makefile b/Makefile index d519fadee39..2d19d28a271 100644 --- a/Makefile +++ b/Makefile @@ -87,6 +87,20 @@ endif =20 include $(SRC_PATH)/rules.mak =20 +# Create QEMU_PKGVERSION and FULL_VERSION strings +# If PKGVERSION is set, use that; otherwise get version and -dirty status = from git +QEMU_PKGVERSION :=3D $(if $(PKGVERSION),$(PKGVERSION),$(shell \ + cd $(SRC_PATH); \ + if test -d .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 :=3D $(if $(QEMU_PKGVERSION),$(VERSION) ($(QEMU_PKGVERSION)),= $(VERSION)) + GENERATED_FILES =3D qemu-version.h config-host.h qemu-options.def =20 #see Makefile.objs for the definition of QAPI_MODULES @@ -391,23 +405,8 @@ all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-= all modules =20 qemu-version.h: FORCE $(call quiet-command, \ - (cd $(SRC_PATH); \ - if test -n "$(PKGVERSION)"; then \ - pkgvers=3D"$(PKGVERSION)"; \ - else \ - if test -d .git; then \ - pkgvers=3D$$(git describe --match 'v*' 2>/dev/null | tr -d '\n');\ - if ! git diff-index --quiet HEAD &>/dev/null; then \ - pkgvers=3D"$${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 $@; \ --=20 2.20.1 From nobody Mon Apr 29 03:50:01 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) 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 1549033416707520.8756946275404; Fri, 1 Feb 2019 07:03:36 -0800 (PST) Received: from localhost ([127.0.0.1]:56117 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpaLu-00007W-NB for importer@patchew.org; Fri, 01 Feb 2019 10:03:34 -0500 Received: from eggs.gnu.org ([209.51.188.92]:38941) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpa9f-0008Q4-BG for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:56 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpa9e-0004E4-Hk for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:55 -0500 Received: from mail-wr1-x42f.google.com ([2a00:1450:4864:20::42f]:36872) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpa9e-0004Db-B6 for qemu-devel@nongnu.org; Fri, 01 Feb 2019 09:50:54 -0500 Received: by mail-wr1-x42f.google.com with SMTP id s12so7397181wrt.4 for ; Fri, 01 Feb 2019 06:50:54 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c21sm12988975wre.71.2019.02.01.06.50.51 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:52 -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=R3OZlwN0C+JurXZGsDqJU+0OVCxF+OtX907vOXRxbwU=; b=A/AmVQ99h3iW8+cFveSQAqJALKxlggqAIA0TJKked7Q/yTTFLjlQ5HCX7LQkx1b1mv nZ9Aj5sz+m2uFHUOet1HD+/lNc/b+R8iSJZGmpkVTwolB4Xt0CbPdZCQ4rsCn3gFOpSM y/o0ob+ggfg9HFIQuUjKNuureAd+JHDwdT3bU= 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=R3OZlwN0C+JurXZGsDqJU+0OVCxF+OtX907vOXRxbwU=; b=qCfibdajWud5Eadz5mRPrry35Dk9CLU3n/nB7wJ6XNZ4mTXKdHiPE6Q/AvCKW2CbfU pVRvnNFJPQsS4R0pDtQfRqAGTI6PgMED37ZPV1RHe8G9dhARu3Nq/wh/EceQ1Q+UMmTF kMorHhbTDMMAED2misKg4YGqtqKOJOrVSLkgJjt4gJSWJdY6q5wugp8Ovns2ILWWQ/g0 wjeP8eQ5xkvl03kHecx6zd2sjRK6E8fVrMtvaxWdKHG0++rHCinZGeXO0lEuyBYvWrL1 TK/jUbrK1j+O3Mhn/99s/lRzfzRfvY+iJEYE3yodKD0yqHiSCs8vQCsz3WVBYZlKnNfR poTQ== X-Gm-Message-State: AHQUAuab074CLgcN1LFFjDgDCh9Bk4dJFeJDX183GXLhYJoH/pefKMnx rQMU9KN4crhMhUSzJPuHbwZ1l6QxGuBxGQ== X-Google-Smtp-Source: AHgI3IZyfkd3dVBz44k+DTbPMMm1vddyYsxWbrG/IUFyReYZYbDOQFH8WrsS2qipwL7mr7kbF6+hUg== X-Received: by 2002:adf:f648:: with SMTP id x8mr2246168wrp.235.1549032653241; Fri, 01 Feb 2019 06:50:53 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Fri, 1 Feb 2019 14:50:35 +0000 Message-Id: <20190201145035.22739-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190201145035.22739-1-peter.maydell@linaro.org> References: <20190201145035.22739-1-peter.maydell@linaro.org> MIME-Version: 1.0 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::42f Subject: [Qemu-devel] [PATCH 11/11] docs/conf.py: Don't hard-code QEMU version 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, Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Don't hard-code the QEMU version number into conf.py. Instead we either pass it to sphinx-build on the command line, or (if doing a standalone Sphinx run in a readthedocs.org setup) extract it from the VERSION file. Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e --- Makefile | 2 +- docs/conf.py | 21 ++++++++++++++++----- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 2d19d28a271..e342242d268 100644 --- a/Makefile +++ b/Makefile @@ -863,7 +863,7 @@ docs/version.texi: $(SRC_PATH)/VERSION sphinxdocs: docs/devel/index.html docs/interop/index.html =20 # Canned command to build a single manual -build-manual =3D $(call quiet-command,sphinx-build $(if $(V),,-q) -b html = -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1") +build-manual =3D $(call quiet-command,sphinx-build $(if $(V),,-q) -b html = -D version=3D$(VERSION) -D release=3D"$(FULL_VERSION)" -d .doctrees/$1 $(SR= C_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1") # We assume all RST files in the manual's directory are used in it manual-deps =3D $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/= conf.py $(SRC_PATH)/docs/conf.py =20 diff --git a/docs/conf.py b/docs/conf.py index 6a334f545ec..0842d44e930 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,11 +75,22 @@ author =3D 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. -# -# The short X.Y version. -version =3D u'4.0' -# The full version, including alpha/beta/rc tags. -release =3D u'4.0' + +# 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 =3D None + with open(os.path.join(qemu_docdir, '../VERSION')) as f: + extracted_version =3D f.readline().strip() +except: + pass +finally: + if extracted_version: + version =3D release =3D extracted_version + else: + version =3D release =3D "unknown version" =20 # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. --=20 2.20.1