doc: Create directory structure

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 <[email protected]> Signed-off-by: Ben Pfaff <[email protected]>
cechu66 · Dec 12, 2016 · 11820a1 · 11820a1
1 parent daf5079
commit 11820a1
Show file tree

Hide file tree

Showing 11 changed files with 329 additions and 1 deletion.
diff --git 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
@@ -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
@@ -0,0 +1,31 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -0,0 +1,34 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -1,4 +1,6 @@
 ..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
       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 </intro/install/index>` guide you through
+  installing Open vSwitch (OVS) and Open Virtual Network (OVN) on a variety of
+  different platforms
+- :doc:`Tutorials </tutorials/index>` take you through a series of steps to
+  configure OVS and OVN in sandboxed environments
+- :doc:`Topic guides </topics/index>` provide a high level overview of OVS and
+  OVN internals and operation
+- :doc:`How-to guides </howto/index>` 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 [email protected]
+
+- Looking for specific information? Try the :ref:`genindex`, :ref:`modindex` or
+  the :doc:`detailed table of contents <contents>`.
diff --git a/Documentation/internals/index.rst b/Documentation/internals/index.rst
@@ -0,0 +1,34 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -0,0 +1,35 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -0,0 +1,34 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -0,0 +1,33 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -0,0 +1,34 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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
@@ -0,0 +1,34 @@
+..
+      Copyright (c) 2016, Stephen Finucane <[email protected]>
+
+      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