From nobody Fri Dec 19 04:38:25 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.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=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1586881786; cv=none; d=zohomail.com; s=zohoarc; b=AA7rHnjeo4z0YpexhTHCbUSCTdX+udizVsKpQpjCEpeSslkfkx36QPhy8gBpkdWaQib6xvnq8HWCf7wuVC6SmHBmYcwcaJ8zjv6gluciwXeRi1oaSskMebG6KnH6wPh/WpTY4rFurZEx8i9xvzRU6nPiBE7b7zYDYGmsVbnwAes= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1586881786; h=Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=xzNWaaDL+DDil6WrxdOdqg0SzbyTOIFf6u4kxUXo+R8=; b=P/J9y0At+sq7xd/MNzg2knmykSeU2/63B5b9nRE8Y2KiH4scjXvzjSojBXQzQrLCNeHRRdLy75CH5dCo209p9zMsEUPPkiIMUeL+hOIHvaHEnL1TY9MKH/VlYMu35JtHWE4e1ESqqzyHfRzaLzrfiFVsyPh5vj20YQqBPn+k5UQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 15868817867881013.6626662584243; Tue, 14 Apr 2020 09:29:46 -0700 (PDT) Received: from localhost ([::1]:34041 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jOORV-0003DG-0f for importer@patchew.org; Tue, 14 Apr 2020 12:29:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51706) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jOOOQ-0005KI-VA for qemu-devel@nongnu.org; Tue, 14 Apr 2020 12:26:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jOOOL-0007Dg-48 for qemu-devel@nongnu.org; Tue, 14 Apr 2020 12:26:34 -0400 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]:35016) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jOOOK-0007DQ-Uk for qemu-devel@nongnu.org; Tue, 14 Apr 2020 12:26:29 -0400 Received: by mail-wr1-x42e.google.com with SMTP id x18so10783076wrq.2 for ; Tue, 14 Apr 2020 09:26:28 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id i129sm20003802wmi.20.2020.04.14.09.26.26 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 14 Apr 2020 09:26:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:subject:date:message-id:in-reply-to:references:mime-version :content-transfer-encoding; bh=xzNWaaDL+DDil6WrxdOdqg0SzbyTOIFf6u4kxUXo+R8=; b=p8FLOnJQlBKKGlqEkJaSOwVwWqxkc9kWdvzGo+dkhTod7kSnLZIltUfT4Szs94LBvg cphYOF23UXMOlofy8WrFTUnIAB9K9nxL0sGy/Ob0dz9aqHjXe6X0bbQEJi1hnDzJ+72Y uKt3HibFPTNPY/9KjwubMGVST4S3jXvktleZeasLn1K2YKuFHT0EB24lyepi/0VM2bue qDSuKYqa8U1hUFgn1qQOeqdv5U1kB5XViReNZajSsBByWI8gCuFpdzqzNv4iGYGs9EPX JfcvdH2WDlQ28wWD15PFUUHOCeWbFUM03+CQPSJ4xfwE2OjI8vlhHzIRca09bLsHEIGB 926A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=xzNWaaDL+DDil6WrxdOdqg0SzbyTOIFf6u4kxUXo+R8=; b=sRNIL3nujIFqv1DG/lj2i1YjupQZMi89Cj3/y6ManVt773C9S+Gdj8Qj7BlMVC+4XS t6+sdJOxaHz+s/yMBmQ/3nxTb0NYHWeMdOLt6qT1Y1itmXkC6kTAYyl8V9HgApABqx7Q YVENXWc5cGISc/vBwxHlB/AQ61YyDJSozCfKasXifXVf/qcdqZvS9AGkb5VIXiS8We1Z hc2SjbDwPg6Uby44EIgxZoBenAYnqIuZdErdFyFLJG7w9HROFBdJEg+/kDhBOa7gSf1e y8f/hAz1rhLuqjJrADIivhXw4RC9Qjep9Vp1e21yHwUvIk17Jj5PhE5wkijt/qXmeqKy qXZg== X-Gm-Message-State: AGi0PubEVOSNjfyvFWP3LKNtEi1iTxMeE3IjmdWg4XDc2Uc6CVmaFPzZ N/Lg0NV/F5vqj/mQc+LqnC+b+l/2mnczjA== X-Google-Smtp-Source: APiQypJ52wI0Z300A8zM68XCMbf4CI/I7naew8qUYN0yqqGKRyqF6M9RLH1tuaycVhexz78julrF7w== X-Received: by 2002:adf:e942:: with SMTP id m2mr24518353wrn.364.1586881587647; Tue, 14 Apr 2020 09:26:27 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PULL 11/12] docs: Require Sphinx 1.6 or better Date: Tue, 14 Apr 2020 17:26:12 +0100 Message-Id: <20200414162613.4479-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200414162613.4479-1-peter.maydell@linaro.org> References: <20200414162613.4479-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::42e X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" Versions of Sphinx older than 1.6 can't build all of our documentation, because they are too picky about the syntax of the argument to the option:: directive; see Sphinx bugs #646, #3366: https://github.com/sphinx-doc/sphinx/issues/646 https://github.com/sphinx-doc/sphinx/issues/3366 Trying to build with a 1.4.x Sphinx fails with docs/system/images.rst:4: SEVERE: Duplicate ID: "cmdoption-qcow2-arg-encry= pt" and a 1.5.x Sphinx fails with docs/system/invocation.rst:544: WARNING: Malformed option description '[en= able=3D]PATTERN', should look like "opt", "-opt args", "--opt args", "/opt args" or "+opt args" Update our needs_sphinx setting to indicate that we require at least 1.6. This will allow configure to fall back to "don't build the docs" rather than causing the build to fail entirely, which is probably what most users building on a host old enough to have such an old Sphinx would want; if they do want the docs then they'll have a useful indication of what they need to do (upgrade Sphinx!) rather than a confusing error message. In theory our distro support policy would suggest that we should support building on the Sphinx shipped in those distros, but: * EPEL7 has Sphinx 1.2.3 (which we've never supported!) * Debian Stretch has Sphinx 1.4.8 Trying to get our docs to work with Sphinx 1.4 is not tractable for the 5.0 release and I'm not sure it's worthwhile effort anyway; at least with this change the build as a whole now succeeds. Thanks to John Snow for doing the investigation and testing to confirm what Sphinx versions fail in what ways and what distros shipped what. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- docs/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7768611e89c..d6e173ef77b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,8 +59,10 @@ sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) =20 # If your documentation needs a minimal Sphinx version, state it here. # -# 1.3 is where the 'alabaster' theme was shipped with Sphinx. -needs_sphinx =3D '1.3' +# Sphinx 1.5 and earlier can't build our docs because they are too +# picky about the syntax of the argument to the option:: directive +# (see Sphinx bugs #646, #3366). +needs_sphinx =3D '1.6' =20 # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom --=20 2.20.1