From patchwork Tue Nov 22 18:18:50 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 697863 X-Patchwork-Delegate: rbryant@redhat.com 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 3tNYlp1FDyz9svs for ; Wed, 23 Nov 2016 05:24:38 +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="aO+alVGK"; dkim-atps=neutral Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id 3CE61B9E; Tue, 22 Nov 2016 18:20:17 +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 98842B2E for ; Tue, 22 Nov 2016 18:20:15 +0000 (UTC) X-Greylist: from auto-whitelisted by SQLgrey-1.7.6 Received: from nov-007-i609.relay.mailchannels.net (nov-007-i609.relay.mailchannels.net [46.232.183.163]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 7E48312F for ; Tue, 22 Nov 2016 18:20:11 +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 E3A0F1BD51E for ; Tue, 22 Nov 2016 18:20:06 +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 325361BC495 for ; Tue, 22 Nov 2016 18:20:06 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.88.26.109]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Tue, 22 Nov 2016 18:20:06 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1479838806554:35315624 X-MC-Ingress-Time: 1479838806554 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To: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:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=vzc2eJh+cDVUlDAEfVU71KC9KM2A6rQSKxV2SyxCoj4=; b=aO+alVGKnWol4ZcACk4DUq2c1B qjzqNvXWg7tAW0A3uOrKrXf/RPYFiLUMuOP/LwRZ0UY3B7yOB230lHPvp6MAYVr8kPeRwBRKsjtWK pzvvpthWMYrHoXPX1wJw7k9s76CqIPpTh5WurpBFMdF7FBBHQv8zMxpuRXBumSsQmFCtJI40Fsa5e jhGiEl4lV/34N3LvKE1yTbZMfqD0XvnMzMKKrPVzt22SH88zUfcwdF8uw7ahBgZg3jawKGy1dAnaT ik4TP1f+fDjtQZ1LCpRjKIbz/VkRFyPXF5DWo1AEe8CDwsvEIm/vdkcAO7LJM2Tz2sbQkcFw/gdBz AxBB0DwA==; From: Stephen Finucane To: dev@openvswitch.org Date: Tue, 22 Nov 2016 18:18:50 +0000 Message-Id: <1479838739-26356-6-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1479838739-26356-1-git-send-email-stephen@that.guru> References: <1479838739-26356-1-git-send-email-stephen@that.guru> X-OutGoing-Spam-Status: No, score=-9.2 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 05/14] doc: Create directory structure 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 Create a series of sections, all of which are currently empty, using the general design established by Jacob Kaplan-Moss and the Django project [1]. Five sections are provided: - intro - tutorials - topics - howto - ref - faq - internals The purpose of each section is described in the documents themselves. [1] https://jacobian.org/writing/great-documentation/ Signed-off-by: Stephen Finucane --- Documentation/automake.mk | 10 ++++++++- Documentation/contents.rst | 11 ++++++++++ Documentation/faq/index.rst | 31 +++++++++++++++++++++++++++ Documentation/howto/index.rst | 34 +++++++++++++++++++++++++++++ Documentation/index.rst | 40 +++++++++++++++++++++++++++++++++++ Documentation/internals/index.rst | 34 +++++++++++++++++++++++++++++ Documentation/intro/index.rst | 35 ++++++++++++++++++++++++++++++ Documentation/intro/install/index.rst | 34 +++++++++++++++++++++++++++++ Documentation/ref/index.rst | 33 +++++++++++++++++++++++++++++ Documentation/topics/index.rst | 34 +++++++++++++++++++++++++++++ Documentation/tutorials/index.rst | 34 +++++++++++++++++++++++++++++ 11 files changed, 329 insertions(+), 1 deletion(-) create mode 100644 Documentation/faq/index.rst create mode 100644 Documentation/howto/index.rst create mode 100644 Documentation/internals/index.rst create mode 100644 Documentation/intro/index.rst create mode 100644 Documentation/intro/install/index.rst create mode 100644 Documentation/ref/index.rst create mode 100644 Documentation/topics/index.rst create mode 100644 Documentation/tutorials/index.rst diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 9cf67c6..ad5f488 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -9,7 +9,15 @@ EXTRA_DIST += \ Documentation/_static/logo.png \ Documentation/conf.py \ Documentation/index.rst \ - Documentation/contents.rst + Documentation/contents.rst \ + Documentation/intro/index.rst \ + Documentation/intro/install/index.rst \ + Documentation/tutorials/index.rst \ + Documentation/topics/index.rst \ + Documentation/howto/index.rst \ + Documentation/ref/index.rst \ + Documentation/faq/index.rst \ + Documentation/internals/index.rst # You can set these variables from the command line. SPHINXOPTS = diff --git a/Documentation/contents.rst b/Documentation/contents.rst index 3ecb741..befc8f6 100644 --- a/Documentation/contents.rst +++ b/Documentation/contents.rst @@ -29,3 +29,14 @@ Open vSwitch Documentation Contents :maxdepth: 3 index + +.. toctree:: + :maxdepth: 3 + + intro/index + tutorials/index + topics/index + howto/index + ref/index + faq/index + internals/index diff --git a/Documentation/faq/index.rst b/Documentation/faq/index.rst new file mode 100644 index 0000000..a32f550 --- /dev/null +++ b/Documentation/faq/index.rst @@ -0,0 +1,31 @@ +.. + 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 FAQ +================ + +.. toctree:: + :maxdepth: 2 diff --git a/Documentation/howto/index.rst b/Documentation/howto/index.rst new file mode 100644 index 0000000..1c4d9d2 --- /dev/null +++ b/Documentation/howto/index.rst @@ -0,0 +1,34 @@ +.. + 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. + +============= +How-to Guides +============= + +Answers to common "How do I?"-style questions. For more information on the +topics covered herein, refer to :doc:`/topics/index`. + +.. toctree:: + :maxdepth: 2 diff --git a/Documentation/index.rst b/Documentation/index.rst index 5e9c63d..ee42acd 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,4 +1,6 @@ .. + 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 @@ -25,4 +27,42 @@ Open vSwitch Documentation ========================== +How the Documentation is Organised +---------------------------------- + +The Open vSwitch documentation is organised into multiple sections: + +- :doc:`Installation guides ` guide you through + installing Open vSwitch (OVS) and Open Virtual Network (OVN) on a variety of + different platforms +- :doc:`Tutorials ` take you through a series of steps to + configure OVS and OVN in sandboxed environments +- :doc:`Topic guides ` provide a high level overview of OVS and + OVN internals and operation +- :doc:`How-to guides ` are recipes or use-cases for OVS and OVN. + They are more advanced than the tutorials. + +First Steps +----------- + +**TODO** + +Deeper Dive +----------- + **TODO** + +The Open vSwitch Project +------------------------ + +Learn more about the Open vSwitch project and about how you can contribute: + +**TODO** + +Getting Help +------------- + +- Seeing an issue of potential bug? Report problems to bugs@openvswitch.org + +- Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or + the :doc:`detailed table of contents `. diff --git a/Documentation/internals/index.rst b/Documentation/internals/index.rst new file mode 100644 index 0000000..7c0e0bd --- /dev/null +++ b/Documentation/internals/index.rst @@ -0,0 +1,34 @@ +.. + 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 Internals +====================== + +Information for people who want to know more about the Open vSwitch project +itself and how they might involved. + +.. toctree:: + :maxdepth: 2 diff --git a/Documentation/intro/index.rst b/Documentation/intro/index.rst new file mode 100644 index 0000000..7d42813 --- /dev/null +++ b/Documentation/intro/index.rst @@ -0,0 +1,35 @@ +.. + 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. + +=============== +Getting Started +=============== + +How to get started with Open vSwitch. + +.. toctree:: + :maxdepth: 2 + + install/index diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst new file mode 100644 index 0000000..35dc67c --- /dev/null +++ b/Documentation/intro/install/index.rst @@ -0,0 +1,34 @@ +.. + 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. + +======================= +Installing Open vSwitch +======================= + +A collection of guides detailing how to install Open vSwitch in a variety of +different environments and using different configurations. + +.. toctree:: + :maxdepth: 2 diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst new file mode 100644 index 0000000..cb4f30b --- /dev/null +++ b/Documentation/ref/index.rst @@ -0,0 +1,33 @@ +.. + 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. + +=============== +Reference Guide +=============== + +Man Pages +--------- + +**TODO** diff --git a/Documentation/topics/index.rst b/Documentation/topics/index.rst new file mode 100644 index 0000000..33f1577 --- /dev/null +++ b/Documentation/topics/index.rst @@ -0,0 +1,34 @@ +.. + 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 Deep Dive +====================== + +How Open vSwitch is implemented and, where necessary, why it was implemented +that way. + +.. toctree:: + :maxdepth: 2 diff --git a/Documentation/tutorials/index.rst b/Documentation/tutorials/index.rst new file mode 100644 index 0000000..eebd242 --- /dev/null +++ b/Documentation/tutorials/index.rst @@ -0,0 +1,34 @@ +.. + 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. + +========= +Tutorials +========= + +Getting started with Open vSwitch (OVS) and Open Virtual Network (OVN) for Open +vSwitch. + +.. toctree:: + :maxdepth: 2