From nobody Sun Feb 8 10:48:37 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) client-ip=207.211.31.81; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1574434087; cv=none; d=zohomail.com; s=zohoarc; b=j4dKSVQiXYtnOKTKR1ETmJOUCx4GHxdCtzIsu5pbFi3GgQe7KQhVCa5OBUP4fYCAqgZgKqDFKiPVgRY1yaCdg2xTWaC6mK99eH9pg3uQjB3Y9fe7XgjqHYX56alf+n3ZJ4mXaEkBlNM3gjy02LC/gxWHmJ1WFOb+60+mlXHaf2Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1574434087; h=Content-Type: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=KLzVs13Y7gYLLDXO3z9mmFT8ZTqMQtsRczLpykwdTFE=; b=L2Xe1k2Mwf3LWvDnq4mgKOlRQ631aFTACFAWoYj2tWuoT4TozkhrL35a+KSgfS2qgz1IWqWfH4gCD7CL7FsXZluY2KRynGhEFAzFJDta09nOZPofT75slYFkiacDQaLmQdyPbyWdMIjoJsczATvCzftJGtLKHL1Hy5Otp30Zgnc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-2.mimecast.com [207.211.31.81]) by mx.zohomail.com with SMTPS id 1574434087963668.673617599874; Fri, 22 Nov 2019 06:48:07 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-81-6z5CH2fgNje32rVjQuKXdQ-1; Fri, 22 Nov 2019 09:48:03 -0500 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D0FB51034B3A; Fri, 22 Nov 2019 14:47:53 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A371B2A190; Fri, 22 Nov 2019 14:47:53 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 523DD4E572; Fri, 22 Nov 2019 14:47:53 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id xAMElciu018179 for ; Fri, 22 Nov 2019 09:47:38 -0500 Received: by smtp.corp.redhat.com (Postfix) id 9AEB31036C8E; Fri, 22 Nov 2019 14:47:38 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-49.ams2.redhat.com [10.36.112.49]) by smtp.corp.redhat.com (Postfix) with ESMTP id E3A791036C83; Fri, 22 Nov 2019 14:47:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1574434086; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=KLzVs13Y7gYLLDXO3z9mmFT8ZTqMQtsRczLpykwdTFE=; b=eI8GRm5wYz0qRkw30mChdqk2ZHksCBR19KLva3AQu5lgyf7Xm54jelG/aTTwLcBjnXEmXE +8hW06KRM8Vlg2lsvyodUq+Mj7n8aMKNkzOunbJJqxaGPwO69+R4a0MxirUkm3S6BKV+gJ A9MUad5jV4ptZjCdlknRe2xwzLQKEls= From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Date: Fri, 22 Nov 2019 14:46:55 +0000 Message-Id: <20191122144702.3780548-9-berrange@redhat.com> In-Reply-To: <20191122144702.3780548-1-berrange@redhat.com> References: <20191122144702.3780548-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH v2 08/15] docs: add a minimal style guide for writing RST docs X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-MC-Unique: 6z5CH2fgNje32rVjQuKXdQ-1 X-Mimecast-Spam-Score: 0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Most importantly we document the required heading markup so that we get consistency across the docs. Also mention that docs should have a table of contents if they have headings & are likely longer than one page of text. The 3-space indent rule may sound wierd, but that's what python has recommended and thus what tools like pandoc emit. Rather than try to reindent things to 4-space, just accept this RST norm. Signed-off-by: Daniel P. Berrang=C3=A9 --- docs/docs.html.in | 3 +++ docs/styleguide.rst | 66 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 docs/styleguide.rst diff --git a/docs/docs.html.in b/docs/docs.html.in index f2721964b5..f441769617 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -135,6 +135,9 @@
Contributor guidelines
General hacking guidelines for contributors
=20 +
Docs style guide
+
Style guidelines for reStructuredText docs
+
Project strategy
Sets a vision for future direction & technical choices
=20 diff --git a/docs/styleguide.rst b/docs/styleguide.rst new file mode 100644 index 0000000000..71f29320cb --- /dev/null +++ b/docs/styleguide.rst @@ -0,0 +1,66 @@ +=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 +Documentation style 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 + +.. contents:: + +The following documents some specific libvirt rules for writing docs in +reStructuredText + +Table of contents +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Any document which uses headings and whose content is long enough to cause +scrolling when viewed in the browser must start with a table of contents. +This should be created using the default formatting: + +:: + + .. contents:: + + +Whitespace +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Blocks should be indented with 3 spaces, and no tabs + + +Headings +=3D=3D=3D=3D=3D=3D=3D=3D + +RST allows headings to be created simply by underlining with any punctuati= on +characters. Optionally the text may be overlined to. + +For the sake of consistency, libvirt defines the following style requireme= nt +which allows for 6 levels of headings + +:: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D + Heading 1 + =3D=3D=3D=3D=3D=3D=3D=3D=3D + + + + Heading 2 + =3D=3D=3D=3D=3D=3D=3D=3D=3D + + + + Heading 3 + --------- + + + + Heading 4 + ~~~~~~~~~ + + + + Heading 5 + ......... + + + + Heading 6 + ^^^^^^^^^ --=20 2.23.0 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list