From patchwork Thu Dec 22 09:54:42 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 708180 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 3tkn1v4JgPz9sBv for ; Thu, 22 Dec 2016 20:54:59 +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="YKxM8850"; dkim-atps=neutral Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 22DE2958; Thu, 22 Dec 2016 09:54:58 +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 8B1B971F for ; Thu, 22 Dec 2016 09:54:56 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from caracal.maple.relay.mailchannels.net (caracal.maple.relay.mailchannels.net [23.83.214.30]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 9D0AACB for ; Thu, 22 Dec 2016 09:54: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 6CE82A14AD for ; Thu, 22 Dec 2016 09:54:54 +0000 (UTC) Received: from one.mxroute.com (ip-10-120-4-226.us-west-2.compute.internal [10.120.4.226]) by relay.mailchannels.net (Postfix) with ESMTPA id B20C1A02F5 for ; Thu, 22 Dec 2016 09:54:53 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.16.27.41]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Thu, 22 Dec 2016 09:54:54 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1482400493954:1407471950 X-MC-Ingress-Time: 1482400493953 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=lJUV85b2L7QJvDIh3NgrJALhIZugY9gFmuBLboB2pIE=; b=YKxM88504I3zg2lms376WFdbxR lqdmrifE94kekIVkGosXJRRMhG0kB7VoHKQV1Vn3oABcYY39QzZ9Te/4aNo0AnyiOYcQJHJEQ2OpE UF3XvWXFT7s3TZXQkPZyDyIQPGL+6QC1aw3ALO9dEJb8qlk+ZUGC1bP7SDzeJAJV4jYD05YLyMd7F UdOT8aRAfEStgZuu0hAFkCNp6D9B69O+SNcmJ5QvumqUZIJJ6JfBbsmF/7PgmR+/FL+4gchRpoa2I GKuUKnsXlg03ZBkZ8wgIn7JeqNuEg0MKydoYl1NQ7Pshty9KqiRnB4hjrYolYQdF1dijVFUV2zy/o M9limesQ==; From: Stephen Finucane To: dev@openvswitch.org Date: Thu, 22 Dec 2016 09:54:42 +0000 Message-Id: <20161222095447.23007-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 v2 1/6] doc: Add info on building documentation 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 I know how to do this, but does anyone else? Let's make it obvious and ease the cognitive load on the great folks writing docs. Links to the various packaging guides, previously missing, are included on the main page. Signed-off-by: Stephen Finucane --- Documentation/automake.mk | 4 +- Documentation/index.rst | 7 ++- Documentation/intro/install/documentation.rst | 89 +++++++++++++++++++++++++++ Documentation/intro/install/index.rst | 10 ++- Documentation/requirements.txt | 1 + 5 files changed, 108 insertions(+), 3 deletions(-) create mode 100644 Documentation/intro/install/documentation.rst create mode 100644 Documentation/requirements.txt diff --git a/Documentation/automake.mk b/Documentation/automake.mk index bc8bef3..b488807 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -9,6 +9,7 @@ EXTRA_DIST += \ Documentation/intro/install/index.rst \ Documentation/intro/install/bash-completion.rst \ Documentation/intro/install/debian.rst \ + Documentation/intro/install/documentation.rst \ Documentation/intro/install/dpdk.rst \ Documentation/intro/install/fedora.rst \ Documentation/intro/install/general.rst \ @@ -80,7 +81,8 @@ EXTRA_DIST += \ Documentation/internals/contributing/coding-style.rst \ Documentation/internals/contributing/coding-style-windows.rst \ Documentation/internals/contributing/documentation-style.rst \ - Documentation/internals/contributing/submitting-patches.rst + Documentation/internals/contributing/submitting-patches.rst \ + Documentation/requirements.txt # You can set these variables from the command line. SPHINXOPTS = diff --git a/Documentation/index.rst b/Documentation/index.rst index f410487..32b41e1 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -76,6 +76,10 @@ Deeper Dive - **Reference Guides:** :doc:`ref/index` +- **Packaging:** :doc:`intro/install/debian` | + :doc:`intro/install/rhel` | + :doc:`intro/install/fedora` + The Open vSwitch Project ------------------------ @@ -96,7 +100,8 @@ Learn more about the Open vSwitch project and about how you can contribute: :doc:`internals/committer-responsibilities` | :doc:`internals/committer-grant-revocation` -- **Documentation:** :doc:`internals/contributing/documentation-style` +- **Documentation:** :doc:`internals/contributing/documentation-style` | + :doc:`Building Open vSwitch Documentation ` Getting Help ------------- diff --git a/Documentation/intro/install/documentation.rst b/Documentation/intro/install/documentation.rst new file mode 100644 index 0000000..1160e94 --- /dev/null +++ b/Documentation/intro/install/documentation.rst @@ -0,0 +1,89 @@ +.. + Copyright (c) 2016 Stephen Finucane + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +========================== +Open vSwitch Documentation +========================== + +This document describes how to build the OVS documentation for use offline. A +continuously updated, online version can be found at `docs.openvswitch.org +`__. + +.. note:: + These instructions provide information on building the documentation locally. + For information on writing documentation, refer to + :doc:`/internals/contributing/documentation-style` + +Build Requirements +------------------ + +As described in the :doc:`/internals/contributing/documentation-style`, the +Open vSwitch documentation is written in reStructuredText and built with +Sphinx. A detailed guide on installing Sphinx in many environments is available +on the `Sphinx website`__ but, for most Linux distributions, you can install +with your package manager. For example, on Debian/Ubuntu run:: + + $ sudo apt-get install python-sphinx + +Similarly, on RHEL/Fedora run:: + + $ sudo dnf install python-sphinx + +A ``requirements.txt`` is also provided in the ``/Documentation``, should you +wish to install using ``pip``:: + + $ virtualenv .venv + $ source .venv/bin/activate + $ pip install -r Documentation/requirements.txt + +__ http://www.sphinx-doc.org/install.html + +Configuring +----------- + +It's unlikely that you'll need to customize any aspect of the configuration. +However, the ``Documentation/conf.py`` is the go-to place for all +configuration. This file is well documented and further information is +available on the `Sphinx website`__. + +Building +-------- + +Once Sphinx installed, the documentation can be built using the provided +Makefile targets:: + + $ make htmldocs + +.. important:: + + The ``htmldocs`` target will fail if there are any syntax errors. However, + it won't catch more succint issues such as style or grammar issues. As a + result, you should always inspect changes visually to ensure the result is + as intended. + +Once built, documentation is available in the ``/Documentation/_build`` folder. +Open the root ``index.html`` to browse the documentation. + +__ http://www.sphinx-doc.org/config.html diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst index 0d3ea06..34b014a 100644 --- a/Documentation/intro/install/index.rst +++ b/Documentation/intro/install/index.rst @@ -45,7 +45,6 @@ Installation from Source xenserver userspace dpdk - bash-completion Installation from Packages -------------------------- @@ -60,3 +59,12 @@ provided below. debian fedora rhel + +Others +------ + +.. toctree:: + :maxdepth: 2 + + bash-completion + documentation diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt new file mode 100644 index 0000000..354d3d0 --- /dev/null +++ b/Documentation/requirements.txt @@ -0,0 +1 @@ +sphinx>=1.3