From patchwork Sat Dec 17 22:23:37 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 706728 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3th1tz3ynqz9vFF for ; Sun, 18 Dec 2016 09:24:27 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="li3YQfuY"; dkim-atps=neutral Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 856627A4; Sat, 17 Dec 2016 22:24:00 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id 620589C for ; Sat, 17 Dec 2016 22:23:56 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from cat.maple.relay.mailchannels.net (cat.maple.relay.mailchannels.net [23.83.214.31]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 3890914B for ; Sat, 17 Dec 2016 22:23:55 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id C49ED100352 for ; Sat, 17 Dec 2016 22:23:53 +0000 (UTC) Received: from one.mxroute.com (ip-10-229-2-62.us-west-2.compute.internal [10.229.2.62]) by relay.mailchannels.net (Postfix) with ESMTPA id 4AE491012D6 for ; Sat, 17 Dec 2016 22:23:53 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.90.135.124]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sat, 17 Dec 2016 22:23:53 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1482013433507:1072706388 X-MC-Ingress-Time: 1482013433507 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To:MIME-Version :Content-Type:Content-Transfer-Encoding:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: In-Reply-To:References:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=EY3JlBuvsOkJAk9xVX9B8l03H9bFNjGZW7oZktl+CfQ=; b=li3YQfuYmXFkqWPdb48R+xmNb9 0kTblKb4Slm+638oU7x+x5BllHf+HacK+6F4FBzsDWHAhth8OUBnmtQlP8ynS4MB4XgpPbWeSDc/3 u8WW86Qna1J82AjDkLPQ0rNfoodisStbi+IouIBQYC0aowuK/CUjQeSCMPYm2N1Cd28gu6DjcTeEC ZCHQDpY7C0cFR+IY0M8d7zZVmxeYoBFIKnVr1/NxKw1x7ZbCjlQ/2KZZIOV/WpH4NAnaicbFul4H6 oBf91tzWjVe1o8DKNTP7T0tQXdZDQOzQWnRu3MM69oWEZOVYMF6FBOCAiPfBlwCn2yuvyt3bQIuNu 8WwFGHng==; From: Stephen Finucane To: dev@openvswitch.org Date: Sat, 17 Dec 2016 22:23:37 +0000 Message-Id: <20161217222342.21653-1-stephen@that.guru> X-Mailer: git-send-email 2.9.3 X-AuthUser: stephen@that.guru X-Spam-Status: No, score=-1.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_NONE,T_DKIM_INVALID autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Subject: [ovs-dev] [PATCH 1/6] doc: Add some useful tools for doc editing X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org This has come up on the mailing list. Let's document it! Signed-off-by: Stephen Finucane --- .../internals/contributing/documentation-style.rst | 29 +++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index c32921e..02a8d50 100644 --- a/Documentation/internals/contributing/documentation-style.rst +++ b/Documentation/internals/contributing/documentation-style.rst @@ -35,12 +35,15 @@ documents found in the project tree. reStructuredText vs. Sphinx --------------------------- -reStructuredText (reST) is the syntax, while Sphinx is a documentation +`reStructuredText (reST)`__ is the syntax, while `Sphinx`__ is a documentation generator. Sphinx introduces a number of extensions to reST, like the ``:ref:`` role, which can and should be used in documentation, but these will not work correctly on GitHub. As such, these extensions should not be used in any documentation in the root level, such as the ``README``. +__ http://docutils.sourceforge.net/rst.html +__ http://www.sphinx-doc.org/ + reST Conventions ---------------- @@ -324,9 +327,29 @@ vSwitch documentation. These guidelines are based on the `IBM Style Guide Avoid "please" and "thank you" +Helpful Tools +------------- + +There are a number of tools, online and offline, which can be used to preview +documents are you edit them: + +- `rst.ninjs.org `__ + + An online rST editor/previewer + +- `ReText `__ + + A simple but powerful editor for Markdown and reStructuredText. ReText is + written in Python. + +- `restview `__ + + A viewer for ReStructuredText documents that renders them on the fly. + Useful Links ------------ -* `Quick reStructuredText +- `Quick reStructuredText `__ -* `Sphinx Documentation `__ + +- `Sphinx Documentation `__