[ovs-dev] [PATCH 05/14] doc: Create directory structure

Stephen Finucane stephen at that.guru
Tue Nov 22 18:18:50 UTC 2016


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 <stephen at that.guru>
---
 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 <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
       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 bugs at openvswitch.org
+
+- 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
new file mode 100644
index 0000000..7c0e0bd
--- /dev/null
+++ b/Documentation/internals/index.rst
@@ -0,0 +1,34 @@
+..
+      Copyright (c) 2016, Stephen Finucane <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
+      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 <stephen at that.guru>
+
+      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
-- 
2.7.4



More information about the dev mailing list