Add and update docs for doc/source directory

Add the following items for doc/source/contributor
1. add file for documentation, gerrit, jenkins, launchpad
   and releasenotes
2. Add README for admin, cli, install and contributor

Change-Id: I6463a9e4df64a2e2e3cb0043f9e5aaa92aeb0519

doc/source/admin/README.rst

@@ -0,0 +1,7 @@
+===============================================
+Zun Administration Documentation (source/admin)
+===============================================
+
+
+This directory is intended to hold any documentation that is related
+to how to run or operate Zun.

doc/source/cli/README.rst

@@ -0,0 +1,10 @@
+==================================
+Zun CLI Documentation (source/cli)
+==================================
+
+
+This directory is intended to hold any documentation that relates to
+Zun's Command Line Interface. Note that this directory is intended for
+basic descriptions of the commands supported, similar to what you would
+find with a 'man page'. Tutorials or step-by-step guides should go into
+'doc/source/admin' or 'doc/source/user' depending on the target audience.

doc/source/cli/index.rst

@@ -0,0 +1,6 @@
+======================
+Zun Command Line Guide
+======================
+
+TODO: There is currently no command line guide for Zun. The work will be
+tracked here: https://blueprints.launchpad.net/zun/+spec/zun-cli-guide

doc/source/configuration/README.rst

@@ -0,0 +1,10 @@
+======================================================
+Zun Configuration Documentation (source/configuration)
+======================================================
+
+
+This directory is intended to hold any documentation that relates
+to how to configure Zun. It is intended that some of this content
+be automatically generated in the future. At the moment, however,
+it is not. Changes to configuration options for Zun or its drivers
+needs to be put under this directory.

doc/source/contributor/README.rst

@@ -0,0 +1,10 @@
+==================================================
+Zun Contributor Documentation (source/contributor)
+==================================================
+
+
+This directory is intended to hold any documentation that relates to
+how to contirbute to Zun or how the project is managed. Some of this
+content was previous under 'developer' in openstack-manuals. The content
+of the documentation, however, goes beyond just developers to anyone
+contributing to the project, thus the change in naming.

doc/source/contributor/documentation.rst

@@ -0,0 +1,101 @@
+Contributing Documentation to Zun
+=================================
+
+Zun's documentation has been moved from the openstack-manuals repository
+to the ``docs`` directory in the Zun repository.  This makes it even more
+important that Zun add and maintain good documentation.
+
+
+This page provides guidance on how to provide documentation for those
+who may not have previously been active writing documentation for
+OpenStack.
+
+Using RST
+---------
+
+OpenStack documentation uses reStructuredText to write documentation.
+The files end with a ``.rst`` extension.  The ``.rst`` files are then
+processed by Sphinx to build HTML based on the RST files.
+
+.. note::
+   Files that are to be included using the ``.. include::`` directive in an
+   RST file should use the ``.inc`` extension.  If you instead use the ``.rst``
+   this will result in the RST file being processed twice during the build and
+   cause Sphinx to generate a warning during the build.
+
+reStructuredText is a powerful language for generating web pages.  The
+documentation team has put together an `RST conventions`_ page with information
+and links related to RST.
+
+.. _RST conventions: https://docs.openstack.org/contributor-guide/rst-conv.html
+
+Building Zun's Documentation
+----------------------------
+
+To build documentation the following command should be used:
+
+.. code-block:: console
+
+   tox -e docs,pep8
+
+When building documentation it is important to also run pep8 as it is easy
+to introduce pep8 failures when adding documentation.  Currently, we do not
+have the build configured to treat warnings as errors, so it is also important
+to check the build output to ensure that no warnings are produced by Sphinx.
+
+.. note::
+
+   Many Sphinx warnings result in improperly formatted pages being generated.
+
+During the documentation build a number of things happen:
+
+   * All of the RST files under ``doc/source`` are processed and built.
+
+      * The openstackdocs theme is applied to all of the files so that they
+        will look consistent with all the other OpenStack documentation.
+      * The resulting HTML is put into ``doc/build/html``.
+
+   * Sample files like zun.conf.sample are generated and put into
+     ``doc/soure/_static``.
+
+After the build completes the results may be accessed via a web browser in
+the ``doc/build/html`` directory structure.
+
+Review and Release Process
+--------------------------
+Documentation changes go through the same review process as all other changes.
+
+.. note::
+
+   Reviewers can see the resulting web page output by clicking on
+   ``gate-zun-docs-ubuntu-xenial``!
+
+Once a patch is approved it is immediately released to the docs.openstack.org
+website and can be seen under Zun's Documentation Page at
+https://docs.openstack.org/zun/latest .  When a new release is cut a
+snapshot of that documentation will be kept at
+https://docs.openstack.org/zun/<release> .  Changes from master can be
+backported to previous branches if necessary.
+
+
+Doc Directory Structure
+-----------------------
+The main location for Zun's documentation is the ``doc/source`` directory.
+The top level index file that is seen at
+`https://docs.openstack/org/zun/latest`_ resides here as well as the
+``conf.py`` file which is used to set a number of parameters for the build
+of OpenStack's documentation.
+
+Each of the directories under source are for specific kinds of documentation
+as is documented in the ``README`` in each directory:
+
+.. toctree::
+   :maxdepth: 1
+
+   ../admin/README
+   ../cli/README
+   ../configuration/README
+   ../contributor/README
+   ../install/README
+
+.. _https://docs.openstack/org/zun/latest: https://docs.openstack/org/zun/latest

doc/source/contributor/gerrit.rst

@@ -0,0 +1,16 @@
+Code Reviews with Gerrit
+========================
+
+Zun uses the `Gerrit`_ tool to review proposed code changes. The review site
+is https://review.openstack.org.
+
+Gerrit is a complete replacement for Github pull requests. `All Github pull
+requests to the Zun repository will be ignored`.
+
+See `Gerrit Workflow Quick Reference`_ for information about how to get
+started using Gerrit. See `Development Workflow`_ for more detailed
+documentation on how to work with Gerrit.
+
+.. _Gerrit: https://bugs.chromium.org/p/gerrit/
+.. _Development Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow
+.. _Gerrit Workflow Quick Reference: https://docs.openstack.org/infra/manual/developers.html#development-workflow

doc/source/contributor/index.rst

@@ -1,6 +1,15 @@
 Contributor's Guide
 ===================
 
+In this section you will find information on how to contribute to Zun.
+Content includes architectural overviews, tips and tricks for setting up
+a development environment, and information on Cinder's lower level programming
+APIs.
+
+
+HowTos and Tutorials
+--------------------
+
 If you are new to Zun, this section contains information that should help
 you quickly get started.
 
@@ -29,3 +38,22 @@ contribute effectively towards code standards to the project.
 
   Adding a New API Method <api-microversion>
   Changing Zun DB Objects <objects>
+
+
+Documentation Contribution
+--------------------------
+.. toctree::
+   :maxdepth: 2
+
+   documentation
+
+
+Other Resources
+---------------
+.. toctree::
+   :maxdepth: 3
+
+   launchpad
+   gerrit
+   jenkins
+   releasenotes

doc/source/contributor/jenkins.rst

@@ -0,0 +1,22 @@
+Continuous Integration with Jenkins
+===================================
+
+Zun uses a `Jenkins <http://jenkins-ci.org>`_ server to automate development
+tasks.
+
+Jenkins performs tasks such as:
+
+`gate-zun-pep8-ubuntu-xenial`
+    Run PEP8 checks on proposed code changes that have been reviewed.
+
+`gate-zun-python27-ubuntu-xenial`
+    Run unit tests using python2.7 on proposed code changes that have been
+    reviewed.
+
+`gate-zun-python35`
+    Run unit tests using python3.5 on proposed code changes that have been
+    reviewed.
+
+`gate-zun-docs-ubuntu-xenial`
+    Build this documentation and push it to `OpenStack Zun
+    <https://docs.openstack.org/zun/latest/>`_.

doc/source/contributor/launchpad.rst

@@ -0,0 +1,54 @@
+Project hosting with Launchpad
+==============================
+
+`Launchpad`_ hosts the Zun project. The Zun project homepage on
+Launchpad is http://launchpad.net/zun.
+
+
+Mailing list
+------------
+
+The mailing list email is ``openstack@lists.openstack.org``. This is a common
+mailing list across the OpenStack projects. To participate in the mailing list:
+
+#. Subscribe to the list at
+http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack
+
+The mailing list archives are at http://lists.openstack.org/pipermail/openstack/.
+
+
+Bug tracking
+------------
+
+Report Zun bugs at https://bugs.launchpad.net/zun
+
+Launchpad credentials
+---------------------
+
+Creating a login on Launchpad is important even if you don't use the Launchpad
+site itself, since Launchpad credentials are used for logging in on several
+OpenStack-related sites. These sites include:
+
+ * `Wiki`_
+ * Gerrit (see :doc:`gerrit`)
+ * Jenkins (see :doc:`jenkins`)
+
+Feature requests (Blueprints)
+-----------------------------
+
+Zun uses Launchpad Blueprints to track feature requests. Blueprints are at
+https://blueprints.launchpad.net/zun.
+
+Technical support (Answers)
+---------------------------
+
+Zun no longer uses Launchpad Answers to track Zun technical support questions.
+
+Note that `Ask OpenStack`_ (which is not hosted on Launchpad) can
+be used for technical support requests.
+
+.. _Launchpad: https://launchpad.net
+.. _Wiki: https://wiki.openstack.org/wiki/Main_Page
+.. _Zun Team: https://launchpad.net/~zun
+.. _OpenStack Team: https://launchpad.net/~openstack
+.. _Ask OpenStack: https://ask.openstack.org

doc/source/contributor/quickstart.rst

@@ -20,10 +20,10 @@ This session has been tested on Ubuntu 16.04 (Xenial) only.
 Clone devstack::
 
     # Create a root directory for devstack if needed
-    sudo mkdir -p /opt/stack
+    $ sudo mkdir -p /opt/stack
-    sudo chown $USER /opt/stack
+    $ sudo chown $USER /opt/stack
 
-    git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack
+    $ git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack
 
 We will run devstack with minimal local.conf settings required to enable
 required OpenStack services::
@@ -44,22 +44,22 @@ required OpenStack services::
     # enable_plugin zun-ui https://git.openstack.org/openstack/zun-ui
     END
 
-More devstack configuration information can be found at
+More devstack configuration information can be found at `Devstack Configuration
-https://docs.openstack.org/devstack/latest/configuration.html
+<https://docs.openstack.org/devstack/latest/configuration.html>`_
 
-More neutron configuration information can be found at
+More neutron configuration information can be found at `Devstack Neutron
-https://docs.openstack.org/devstack/latest/guides/neutron.html
+Configuration <https://docs.openstack.org/devstack/latest/guides/neutron.html>`_
 
 Run devstack::
 
-    cd /opt/stack/devstack
+    $ cd /opt/stack/devstack
-    ./stack.sh
+    $ ./stack.sh
 
 Prepare your session to be able to use the various openstack clients including
 nova, neutron, and glance. Create a new shell, and source the devstack openrc
 script::
 
-    source /opt/stack/devstack/openrc admin admin
+    $ source /opt/stack/devstack/openrc admin admin
 
 Using the service
 =================
@@ -102,10 +102,10 @@ for more information.
 On the second host, clone devstack::
 
     # Create a root directory for devstack if needed
-    sudo mkdir -p /opt/stack
+    $ sudo mkdir -p /opt/stack
-    sudo chown $USER /opt/stack
+    $ sudo chown $USER /opt/stack
 
-    git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack
+    $ git clone https://git.openstack.org/openstack-dev/devstack /opt/stack/devstack
 
 The second host will only need zun-compute service along with kuryr-libnetwork
 support. You also need to tell devstack where the SERVICE_HOST is::
@@ -141,8 +141,8 @@ support. You also need to tell devstack where the SERVICE_HOST is::
 
 Run devstack::
 
-    cd /opt/stack/devstack
+    $ cd /opt/stack/devstack
-    ./stack.sh
+    $ ./stack.sh
 
 On the controller host, you can see 2 zun-compute hosts available::
 

doc/source/contributor/releasenotes.rst

@@ -0,0 +1,48 @@
+Release notes
+=============
+
+The release notes for a patch should be included in the patch.
+
+If the following applies to the patch, a release note is required:
+
+* Upgrades
+
+  * The deployer needs to take an action when upgrading
+  * A new config option is added that the deployer should consider changing
+    from the default
+  * A configuration option is deprecated or removed
+
+* Features
+
+  * A new feature or driver is implemented
+  * Feature is deprecated or removed
+  * Current behavior is changed
+
+* Bugs
+
+  * A security bug is fixed
+  * A long-standing or important bug is fixed
+
+* APIs
+
+  * REST API changes
+
+Zun uses `reno <https://docs.openstack.org/reno/latest/>`_ to
+generate release notes. Please read the docs for details. In summary, use
+
+.. code-block:: bash
+
+  $ tox -e venv -- reno new <bug-,bp-,whatever>
+
+Then edit the sample file that was created and push it with your change.
+
+To see the results:
+
+.. code-block:: bash
+
+  $ git commit  # Commit the change because reno scans git log.
+
+  $ tox -e releasenotes
+
+Then look at the generated release notes files in releasenotes/build/html in
+your favorite browser.

doc/source/index.rst

@@ -18,14 +18,14 @@ Zun is an OpenStack Container service. It aims to provide an OpenStack API for
 provisioning and managing containerized workload on OpenStack.
 
 Admin Guide
------------
+~~~~~~~~~~~
 .. toctree::
    :maxdepth: 1
 
    admin/index
 
 Contributor Guide
------------------
+~~~~~~~~~~~~~~~~~
 .. toctree::
    :glob:
    :maxdepth: 2
@@ -33,14 +33,22 @@ Contributor Guide
    contributor/index
 
 Installation Guide
-------------------
+~~~~~~~~~~~~~~~~~~
 .. toctree::
    :maxdepth: 1
 
    install/index
 
+Command Line Guide
+~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   cli/index
+
 Configuration Guide
-===================
+~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
@@ -48,7 +56,7 @@ Configuration Guide
    configuration/index
 
 Architecture Concepts
-=====================
+~~~~~~~~~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 1
@@ -56,7 +64,7 @@ Architecture Concepts
    user/filter-scheduler
 
 Indices and tables
-------------------
+~~~~~~~~~~~~~~~~~~
 
 * :ref:`genindex`
 * :ref:`search`

doc/source/install/README.rst

@@ -0,0 +1,15 @@
+===============================================
+Zun Installation Documentation (source/install)
+===============================================
+
+Introduction:
+-------------
+
+This directory is intended to hold any installation documentation for Zun.
+Documentation that explains how to bring Zun up to the point that it is
+ready to use in an OpenStack or standalone environment should be put
+in this directory.
+
+The full spec for organization of documentation may be seen in the
+`OS Manuals Migration Spec
+<https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html>`.