doc: Populate 'internals' section

This is mostly docs moved from the top-level directory and content scraped from the Open vSwitch website source [1]. [1] https://github.com/openvswitch/openvswitch.github.io/ Signed-off-by: Stephen Finucane <[email protected]> Signed-off-by: Ben Pfaff <[email protected]>
eyoung-father · Dec 12, 2016 · d0e53b1 · d0e53b1
1 parent 4f6ec35
commit d0e53b1
Show file tree

Hide file tree

Showing 19 changed files with 720 additions and 455 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
diff --git a/Documentation/automake.mk b/Documentation/automake.mk
@@ -1,9 +1,6 @@
 docs += \
-	Documentation/committer-responsibilities.rst \
-	Documentation/committer-grant-revocation.rst \
 	Documentation/group-selection-method-property.txt \
-	Documentation/OVSDB-replication.rst \
-	Documentation/release-process.rst
+	Documentation/OVSDB-replication.rst
 
 EXTRA_DIST += \
 	Documentation/_static/logo.png \
@@ -17,7 +14,20 @@ EXTRA_DIST += \
 	Documentation/howto/index.rst \
 	Documentation/ref/index.rst \
 	Documentation/faq/index.rst \
-	Documentation/internals/index.rst
+	Documentation/internals/index.rst \
+	Documentation/internals/authors.rst \
+	Documentation/internals/bugs.rst \
+	Documentation/internals/committer-grant-revocation.rst \
+	Documentation/internals/committer-responsibilities.rst \
+	Documentation/internals/mailing-lists.rst \
+	Documentation/internals/maintainers.rst \
+	Documentation/internals/release-process.rst \
+	Documentation/internals/security.rst \
+	Documentation/internals/contributing/index.rst \
+	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
 
 # You can set these variables from the command line.
 SPHINXOPTS =

diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -57,7 +57,21 @@ The Open vSwitch Project
 
 Learn more about the Open vSwitch project and about how you can contribute:
 
-**TODO**
+- **Community:** :doc:`internals/release-process` |
+  :doc:`internals/authors` |
+  :doc:`internals/mailing-lists` |
+  :doc:`internals/bugs` |
+  :doc:`internals/security`
+
+- **Contributing:** :doc:`internals/contributing/submitting-patches` |
+  :doc:`internals/contributing/coding-style` |
+  :doc:`internals/contributing/coding-style-windows`
+
+- **Maintaining:** :doc:`internals/maintainers` |
+  :doc:`internals/committer-responsibilities` |
+  :doc:`internals/committer-grant-revocation`
+
+- **Documentation:** :doc:`internals/contributing/documentation-style`
 
 Getting Help
 -------------

diff --git a/Documentation/internals/authors.rst b/Documentation/internals/authors.rst
@@ -0,0 +1,24 @@
+..
+      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.
+
+.. include:: ../../AUTHORS.rst
diff --git a/REPORTING-BUGS.rst → Documentation/internals/bugs.rst b/REPORTING-BUGS.rst → Documentation/internals/bugs.rst
@@ -31,7 +31,7 @@ they can be fixed as quickly as possible.
 
 Please report bugs by sending email to [email protected].
 
-For reporting security vulnerabilities, please read SECURITY.rst.
+For reporting security vulnerabilities, please read :doc:`security`.
 
 The most important parts of your bug report are the following:
 

diff --git a/Documentation/committer-grant-revocation.rst → .../internals/committer-grant-revocation.rst b/Documentation/committer-grant-revocation.rst → .../internals/committer-grant-revocation.rst
@@ -269,7 +269,7 @@ Invitation to Accepted Committer
     Developers with commit access must agree to fulfill specific
     responsibilities described in the source repository:
 
-        /Documentation/committer-responsibilities.rst
+        /Documentation/internals/committer-responsibilities.rst
 
     Please let us know if you would like to accept commit access and if so that
     you agree to fulfill these responsibilities. Once we receive your response

diff --git a/Documentation/committer-responsibilities.rst → .../internals/committer-responsibilities.rst b/Documentation/committer-responsibilities.rst → .../internals/committer-responsibilities.rst
@@ -28,8 +28,8 @@ Expectations for Developers with Open vSwitch Repo Access
 Pre-requisites
 --------------
 
-Be familiar with the `coding style <../../CodingStyle.rst>`__ and `contributing
-<../../CONTRIBUTING.rst>`__ guides.
+Be familar with the guidlines and standards defined in
+:doc:`contributing/index`.
 
 Review
 ------
@@ -88,9 +88,9 @@ bring it up on the mailing list. If you explain the use of "Signed-off-by:" to
 a new developer, explain not just how but why, since the intended meaning of
 "Signed-off-by:" is more important than the syntax. As part of your
 explanation, quote or provide a URL to the Developer's Certificate of Origin in
-the `contributing guide <../../CONTRIBUTING.rst>`__.
+:doc:`contributing/submitting-patches`.
 
 Use Reported-by: and Tested-by: tags in commit messages to indicate the
 source of a bug report.
 
-Keep the `AUTHORS <../../AUTHORS>`__ file up to date.
+Keep the ``AUTHORS.rst`` file up to date.
diff --git a/datapath-windows/CodingStyle.rst → ...als/contributing/coding-style-windows.rst b/datapath-windows/CodingStyle.rst → ...als/contributing/coding-style-windows.rst
@@ -25,10 +25,10 @@
 Open vSwitch Windows Datapath Coding Style
 ==========================================
 
-The coding style described in the Open vSwitch distribution gives the
-flexiblity for each platform to use its own coding style for the kernel
-datapath.  This file describes the specific coding style used in most of the C
-files in the Windows kernel datapath of the Open vSwitch distribution.
+The :doc:`coding style <coding-style>` guide gives the flexiblity for each
+platform to use its own coding style for the kernel datapath.  This file
+describes the specific coding style used in most of the C files in the Windows
+kernel datapath of the Open vSwitch distribution.
 
 Most of the coding conventions applicable for the Open vSwitch distribution are
 applicable to the Windows kernel datapath as well.  There are some exceptions

diff --git a/CodingStyle.rst → ...n/internals/contributing/coding-style.rst b/CodingStyle.rst → ...n/internals/contributing/coding-style.rst
@@ -28,7 +28,7 @@ Open vSwitch Coding Style
 This file describes the coding style used in most C files in the Open vSwitch
 distribution. However, Linux kernel code datapath directory follows the Linux
 kernel's established coding conventions. For the Windows kernel datapath code,
-use the coding style described in datapath-windows/CodingStyle.
+use the coding style described in :doc:`coding-style-windows`.
 
 The following GNU indent options approximate this style.
 

diff --git a/DocumentationStyle.rst → ...nals/contributing/documentation-style.rst b/DocumentationStyle.rst → ...nals/contributing/documentation-style.rst
@@ -47,8 +47,8 @@ reST Conventions
 Basics
 ~~~~~~
 
-Many of the basic documentation guidelines match those of the `coding style
-guide <CodingStyle.rst>`__.
+Many of the basic documentation guidelines match those of the
+:doc:`coding-style`.
 
 - Use reStructuredText (reST) for all documentation.
 

diff --git a/Documentation/internals/contributing/index.rst b/Documentation/internals/contributing/index.rst
@@ -0,0 +1,36 @@
+..
+      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.
+
+============================
+Contributing to Open vSwitch
+============================
+
+The below guides provide information on contributing to Open vSwitch itself.
+
+.. toctree::
+   :maxdepth: 2
+
+   submitting-patches
+   coding-style
+   coding-style-windows
+   documentation-style