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
This commit is contained in:
junboli 2017-10-10 16:11:21 +08:00
parent a386cbe0ad
commit d731c27118
14 changed files with 356 additions and 21 deletions

View File

@ -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.

10
doc/source/cli/README.rst Normal file
View File

@ -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.

6
doc/source/cli/index.rst Normal file
View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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/>`_.

View File

@ -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

View File

@ -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 chown $USER /opt/stack
$ sudo mkdir -p /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
https://docs.openstack.org/devstack/latest/configuration.html
More devstack configuration information can be found at `Devstack Configuration
<https://docs.openstack.org/devstack/latest/configuration.html>`_
More neutron configuration information can be found at
https://docs.openstack.org/devstack/latest/guides/neutron.html
More neutron configuration information can be found at `Devstack Neutron
Configuration <https://docs.openstack.org/devstack/latest/guides/neutron.html>`_
Run devstack::
cd /opt/stack/devstack
./stack.sh
$ cd /opt/stack/devstack
$ ./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 chown $USER /opt/stack
$ sudo mkdir -p /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
./stack.sh
$ cd /opt/stack/devstack
$ ./stack.sh
On the controller host, you can see 2 zun-compute hosts available::

View File

@ -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.

View File

@ -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`

View File

@ -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>`.