diff --git a/doc/source/admin/README.rst b/doc/source/admin/README.rst new file mode 100644 index 000000000..8ba6efb58 --- /dev/null +++ b/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. diff --git a/doc/source/cli/README.rst b/doc/source/cli/README.rst new file mode 100644 index 000000000..a5dded7e6 --- /dev/null +++ b/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. diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst new file mode 100644 index 000000000..23a9b9fae --- /dev/null +++ b/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 diff --git a/doc/source/configuration/README.rst b/doc/source/configuration/README.rst new file mode 100644 index 000000000..a873af87a --- /dev/null +++ b/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. diff --git a/doc/source/contributor/README.rst b/doc/source/contributor/README.rst new file mode 100644 index 000000000..4388ce757 --- /dev/null +++ b/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. diff --git a/doc/source/contributor/documentation.rst b/doc/source/contributor/documentation.rst new file mode 100644 index 000000000..0175217c3 --- /dev/null +++ b/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/ . 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 diff --git a/doc/source/contributor/gerrit.rst b/doc/source/contributor/gerrit.rst new file mode 100644 index 000000000..660dd5828 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 93d420802..1f41c83e8 100644 --- a/doc/source/contributor/index.rst +++ b/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 Changing Zun DB Objects + + +Documentation Contribution +-------------------------- +.. toctree:: + :maxdepth: 2 + + documentation + + +Other Resources +--------------- +.. toctree:: + :maxdepth: 3 + + launchpad + gerrit + jenkins + releasenotes diff --git a/doc/source/contributor/jenkins.rst b/doc/source/contributor/jenkins.rst new file mode 100644 index 000000000..d51311565 --- /dev/null +++ b/doc/source/contributor/jenkins.rst @@ -0,0 +1,22 @@ +Continuous Integration with Jenkins +=================================== + +Zun uses a `Jenkins `_ 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 + `_. diff --git a/doc/source/contributor/launchpad.rst b/doc/source/contributor/launchpad.rst new file mode 100644 index 000000000..1d5591f21 --- /dev/null +++ b/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 diff --git a/doc/source/contributor/quickstart.rst b/doc/source/contributor/quickstart.rst index 1dfdea78f..010f65e86 100644 --- a/doc/source/contributor/quickstart.rst +++ b/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 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 +`_ -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 `_ 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:: diff --git a/doc/source/contributor/releasenotes.rst b/doc/source/contributor/releasenotes.rst new file mode 100644 index 000000000..558d2a432 --- /dev/null +++ b/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 `_ to +generate release notes. Please read the docs for details. In summary, use + +.. code-block:: bash + + $ tox -e venv -- reno new + +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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 95e119f9c..3a7de3abd 100644 --- a/doc/source/index.rst +++ b/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` diff --git a/doc/source/install/README.rst b/doc/source/install/README.rst new file mode 100644 index 000000000..5b5b2c903 --- /dev/null +++ b/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 +`.