From patchwork Wed Nov 18 16:03:48 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 56944 Delivered-To: patch@linaro.org Received: by 10.112.155.196 with SMTP id vy4csp2645013lbb; Wed, 18 Nov 2015 08:04:18 -0800 (PST) X-Received: by 10.55.20.4 with SMTP id e4mr2183196qkh.61.1447862657745; Wed, 18 Nov 2015 08:04:17 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id k108si2829881qgf.64.2015.11.18.08.04.17; Wed, 18 Nov 2015 08:04:17 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dkim=neutral (body hash did not verify) header.i=@linaro-org.20150623.gappssmtp.com Received: by lists.linaro.org (Postfix, from userid 109) id 1E5AA61A1E; Wed, 18 Nov 2015 16:04:17 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, T_DKIM_INVALID, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 6740A61D3E; Wed, 18 Nov 2015 16:04:10 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 5314861D63; Wed, 18 Nov 2015 16:03:59 +0000 (UTC) Received: from mail-qk0-f181.google.com (mail-qk0-f181.google.com [209.85.220.181]) by lists.linaro.org (Postfix) with ESMTPS id CDA3961A1E for ; Wed, 18 Nov 2015 16:03:53 +0000 (UTC) Received: by qkda6 with SMTP id a6so15427755qkd.3 for ; Wed, 18 Nov 2015 08:03:53 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id; bh=pu1yFSMlPIUP3Hh3TtYMDM18Kfd0ymsIYdRe9EtfHqQ=; b=Jk0PjliVerwrQ8MyvJMC57LeUXoPY5wWwMVdCSvJowbF8e9h2AudihtvLyErZqROAK mWDYsb2NWS6VHhaNcqcW1RK/Q6nEEjyHsNngM5vKfK22Mv7F215cYt3YQzBy4ldT3Trl Sap0sQQKvxXo26vklvNrkuxSaQtCGj8S0YdxCntmWmUcDMM8KlxWaDNVZQSaXCnkpJn0 a2CtrNPuGeG5BwdoVbue/sH+o5l1qXDseiBkZ5ykXgVnZCR7VRWPXMxjSvS34f+KJpGp Mp7fe4ZbodaLzjq8+eGe0dh3EbR0bxGMfMBH77KUokJ9PJvrklU0ETqsEQUbZuDngfx/ Lrcg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=pu1yFSMlPIUP3Hh3TtYMDM18Kfd0ymsIYdRe9EtfHqQ=; b=UImhbIy0RYqplXPGFzpNaBENun1VgkAqd+GoIhTv0wrb1tuMJjX0YAbZx0G5ekLrUS EY+0TcM/E2BHIdovNCoB4enZZgVV+dnCCsc7U5MDaIw7lval2dxDvtaLFKSzQ6OcqR6P kTFYQER7D4typy5bUDtQQFjXjnNisMtVWRnmfWF+lEIKZNY+7Wheoy+HCNjdmiD6G0rX lvLnZNdtVCDjtvjRGgUbfJ0LZjboWEWdpMNJozsDsi9QcASKHPgRc37xISibBBncMtue hO+d5EPIgCijIUzj9hqjzgZ09lklD8YHU3ZXHD+ww1DM2lACYPWeSfVDLEr6UcVmdvlQ e3zw== X-Gm-Message-State: ALoCoQkemcsvq6o/oJloDuhe08vPQlBxGNr21ersl0eZO21iLcxebB3I83ETYM/ZWO5kr3sSitz2 X-Received: by 10.55.82.193 with SMTP id g184mr2270994qkb.65.1447862633413; Wed, 18 Nov 2015 08:03:53 -0800 (PST) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id d65sm1037235qhc.36.2015.11.18.08.03.52 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 18 Nov 2015 08:03:52 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Wed, 18 Nov 2015 11:03:48 -0500 Message-Id: <1447862628-10701-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.5.0 X-Topics: patch Subject: [lng-odp] [PATCH] CONTRIBUTING: add user doc guidelines X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Mike Holmes Reviewed-by: Bill Fischofer --- CONTRIBUTING | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING b/CONTRIBUTING index 75fb711..4ad964e 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -7,7 +7,8 @@ Table of content: 2. ODP patch expectations as an open source project 3. Common Errors in Patch and Commit Messages 4. Documenting the code -5. References +5. Documenting the user docs +6. References 1. New Development ------------------ @@ -103,7 +104,35 @@ Code without a proper signoff cannot be merged into the mainline. - Functions return values should all be specified using @return or @retval - There should be no doxygen warnings or errors generated. -5. References +5. Documenting the user docs +---------------------------- +- Users guides are stored in asciidoc format in the odp/docs directory and in + sub directories of it as appropriate. +- ODP code references such as types and enums are highlighted using the + + syntax. For example text referring to the type odp_pktio_t would decorate the + type thus:- + +odp_pktio_t+ +- Section heading use the = syntax. For example:- + == Level 1 + Text. + + === Level 2 + Text. +- Code and scripting excerpts are decorated with the block syntax:- + .Optional Title + [source,perl] + ---- + + ---- +- Images are decorated with :- + .Optional Title + image::../images/.png[align="center"] +- The images are stored in the doc/images directory as svg files and rendered as + png and eps during the build process. +- Body text shall wrap at the 80 char point. +- No warnings may be generated by the asciidoc tool. + +6. References ------------- [1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle [2] http://ldn.linuxfoundation.org/book/how-participate-linux-community