From patchwork Mon Dec 9 02:04:51 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Oliver O'Halloran X-Patchwork-Id: 1205851 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [203.11.71.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 47WRNd5ntDz9sP6 for ; Mon, 9 Dec 2019 13:05:21 +1100 (AEDT) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="WJLtw94V"; dkim-atps=neutral Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 47WRNd4cRwzDqKW for ; Mon, 9 Dec 2019 13:05:21 +1100 (AEDT) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gmail.com (client-ip=2607:f8b0:4864:20::543; helo=mail-pg1-x543.google.com; envelope-from=oohall@gmail.com; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: lists.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="WJLtw94V"; dkim-atps=neutral Received: from mail-pg1-x543.google.com (mail-pg1-x543.google.com [IPv6:2607:f8b0:4864:20::543]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 47WRNN73dJzDqJN for ; Mon, 9 Dec 2019 13:05:06 +1100 (AEDT) Received: by mail-pg1-x543.google.com with SMTP id l24so6306024pgk.2 for ; Sun, 08 Dec 2019 18:05:06 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=Fl2J1DvqyBc2uFHSNQsHNSVyojc1wtrF2Tp4A6g702M=; b=WJLtw94VseOHCwIOekOFLkkIfNDcHaMdFyHAgAmeii2lQdeipcXwgYxj4QVl19anUr I9e+IpQqLflQFnTRoEngpVfvDvw1XEBm4+M4K9N2Fd3nsbJwF3pL99yrvuJw9mhue5ed P9VmESJu/dvNhY3GIIFRgffb3U6wuF+C4AGOElYJFOJZOSRc9eIrUn88YGhjJENgmkov DE3HFDCrobZ56Lfmw1zk3hwNGVEUPyLayHPE51/Djnu1cjf9FIi4dKJIVYw0wiNmGond gzj/jZMeJ2U7WpdqzLablr2rtzHT1+VvKEKvpb5xOKb9UOuHVz9n8fY+Ic8Bo38fIcxO LyKw== 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:mime-version :content-transfer-encoding; bh=Fl2J1DvqyBc2uFHSNQsHNSVyojc1wtrF2Tp4A6g702M=; b=YdG/AzrkMHjLuVs8SljcK/kVtuhxwTMpRMNnT22XVRkIC9MxmR9QNHTljlRfo4p9lk x8PiVHzelTySvx6tJ2TDSJzswwlqvoEKqIL51aWPZn6c51B1/TfR/zh/AFA4W561YeVL N0XEXG/BSSIk7BR+bnAOXLT4Jb5LEWFkNoAvNDiQk9ZaHbmKijUI/iuAo8RR0VfUpCEn BLw7Yh89p10k97J7mLajfqNAFDTzDLrseFCTXgJVV40ai/qMNZuRUoZPvYH1hinWoviE aJ0eS1zi2JdBk9vqd6Jd8fKFKdwrDPwCnUoA7Ed7rXzFzYEMlnrmJh+7SXQMFjf1dAGD QxLA== X-Gm-Message-State: APjAAAWOyzwwjyzYnK00QULhOj6DMll8A3b8axGBOExNXq79Ehp7NWxv omD8m/Mu9r+ycyoZSHEzKi4vnHZU X-Google-Smtp-Source: APXvYqxohgxmu9a8U76ZCee9rmHrbq6DQcylafXoGCZddduDoA9SYKm+exjTNSfoTs0paIxK9gGiXA== X-Received: by 2002:a62:7696:: with SMTP id r144mr27152543pfc.177.1575857102533; Sun, 08 Dec 2019 18:05:02 -0800 (PST) Received: from wafer.ozlabs.ibm.com ([122.99.82.10]) by smtp.gmail.com with ESMTPSA id o12sm10370014pjf.19.2019.12.08.18.05.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 08 Dec 2019 18:05:01 -0800 (PST) From: Oliver O'Halloran To: skiboot@lists.ozlabs.org Date: Mon, 9 Dec 2019 13:04:51 +1100 Message-Id: <20191209020451.27755-1-oohall@gmail.com> X-Mailer: git-send-email 2.21.0 MIME-Version: 1.0 Subject: [Skiboot] [PATCH] README.md: Add information on docs X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Add a link to the auto-generated github pages documentation and add instructions for how to build them using Sphinx and some references on reStructuredText. Signed-off-by: Oliver O'Halloran --- .travis.yml | 2 +- README.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 6ddf485d7c83..8080889dd399 100644 --- a/.travis.yml +++ b/.travis.yml @@ -47,7 +47,7 @@ addons: project: name: "open-power/skiboot" description: "Build submitted via Travis CI" - notification_email: stewart@linux.vnet.ibm.com + notification_email: oohall@gmail.com branch_pattern: coverity_scan deploy: diff --git a/README.md b/README.md index c6cdae5cd255..e8743a9ef022 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ Archives: https://lists.ozlabs.org/pipermail/skiboot/ Patchwork: http://patchwork.ozlabs.org/project/skiboot/list/ +Documentation: http://open-power.github.io/skiboot/doc/index.html + ## Overview OPAL firmware (OpenPower Abstraction Layer) comes in several parts. @@ -79,6 +81,30 @@ from here: https://www.kernel.org/pub/tools/crosstool/ When using these compilers add /opt/cross/gcc-4.8.0-nolibc/powerpc64-linux/bin/ to your PATH. Once this is done skiboot can be compiler by just running `make` +### Building Documentation + +We use [Sphinx](http://www.sphinx-doc.org/) to produce various documentation +from reStructuredText (preferred) and Markdown. The Sphinx documentation has +a useful primer for reStructuredText +[here](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). +And the docutils website has a nice [quick +reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html) for the +basic constructes. + +Building on Fedora +``` +dnf install python3-sphinx python3-recommonmark.noarch +pip install -r doc/requirements.txt +make -C doc/ html SPHINXBUILD=sphinx-build-3 +``` + +On Ubuntu: +``` +Patches welcome! +``` + +View the output using `doc/_build/html/index.html` + ## Testing Skiboot comes with a set of unit tests that can be run on your desktop. They can can be run with: