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
parent
a386cbe0ad
commit
d731c27118
7
doc/source/admin/README.rst
Normal file
7
doc/source/admin/README.rst
Normal 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
10
doc/source/cli/README.rst
Normal 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
6
doc/source/cli/index.rst
Normal 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
|
||||
10
doc/source/configuration/README.rst
Normal file
10
doc/source/configuration/README.rst
Normal 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.
|
||||
10
doc/source/contributor/README.rst
Normal file
10
doc/source/contributor/README.rst
Normal 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.
|
||||
101
doc/source/contributor/documentation.rst
Normal file
101
doc/source/contributor/documentation.rst
Normal 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
|
||||
16
doc/source/contributor/gerrit.rst
Normal file
16
doc/source/contributor/gerrit.rst
Normal 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
|
||||
@ -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
|
||||
|
||||
22
doc/source/contributor/jenkins.rst
Normal file
22
doc/source/contributor/jenkins.rst
Normal 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/>`_.
|
||||
54
doc/source/contributor/launchpad.rst
Normal file
54
doc/source/contributor/launchpad.rst
Normal 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
|
||||
@ -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::
|
||||
|
||||
|
||||
48
doc/source/contributor/releasenotes.rst
Normal file
48
doc/source/contributor/releasenotes.rst
Normal 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.
|
||||
@ -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`
|
||||
|
||||
15
doc/source/install/README.rst
Normal file
15
doc/source/install/README.rst
Normal 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>`.
|
||||
Loading…
Reference in New Issue
Block a user