From 79245a62831144df8fcd0d446fd152e5f6fe4ea5 Mon Sep 17 00:00:00 2001 From: "Jay S. Bryant" Date: Thu, 10 Aug 2017 11:24:00 -0500 Subject: [PATCH] [Docs] Add documentation contribution docs Now that we are in charge of managing our documentation I thought we should have a section in the Contributor Guide on how to contribute documentation. This patch adds that. It also resolves build WARNINGS due to the README files I added not being included in any toctrees and adds the missing README file to the install directory. Change-Id: I8e12628b439a400ebd1ee6d691673a16e2c2f9d2 --- doc/source/admin/README.rst | 6 +- doc/source/cli/README.rst | 6 +- doc/source/configuration/README.rst | 6 +- doc/source/contributor/README.rst | 6 +- doc/source/contributor/documentation.rst | 128 +++++++++++++++++++++++ doc/source/contributor/index.rst | 12 ++- doc/source/install/README.rst | 15 +++ doc/source/reference/README.rst | 6 +- doc/source/user/README.rst | 6 +- 9 files changed, 171 insertions(+), 20 deletions(-) create mode 100644 doc/source/contributor/documentation.rst create mode 100644 doc/source/install/README.rst diff --git a/doc/source/admin/README.rst b/doc/source/admin/README.rst index 5debfdd7e60..49c57c16121 100644 --- a/doc/source/admin/README.rst +++ b/doc/source/admin/README.rst @@ -1,6 +1,6 @@ -=================================== -Cinder Administration Documentation -=================================== +================================================== +Cinder Administration Documentation (source/admin) +================================================== Introduction: ------------- diff --git a/doc/source/cli/README.rst b/doc/source/cli/README.rst index 26bbd57dd0a..dda2a38fe4b 100644 --- a/doc/source/cli/README.rst +++ b/doc/source/cli/README.rst @@ -1,6 +1,6 @@ -========================== -Cinder CLI Documentation -========================== +===================================== +Cinder CLI Documentation (source/cli) +===================================== Introduction: ------------- diff --git a/doc/source/configuration/README.rst b/doc/source/configuration/README.rst index e759b64ef06..dd9814b031f 100644 --- a/doc/source/configuration/README.rst +++ b/doc/source/configuration/README.rst @@ -1,6 +1,6 @@ -================================== -Cinder Configuration Documentation -================================== +========================================================= +Cinder Configuration Documentation (source/configuration) +========================================================= Introduction: ------------- diff --git a/doc/source/contributor/README.rst b/doc/source/contributor/README.rst index 127540cb501..684b6804c00 100644 --- a/doc/source/contributor/README.rst +++ b/doc/source/contributor/README.rst @@ -1,6 +1,6 @@ -================================ -Cinder Contributor Documentation -================================ +===================================================== +Cinder Contributor Documentation (source/contributor) +===================================================== Introduction: ------------- diff --git a/doc/source/contributor/documentation.rst b/doc/source/contributor/documentation.rst new file mode 100644 index 00000000000..f7b024f6c54 --- /dev/null +++ b/doc/source/contributor/documentation.rst @@ -0,0 +1,128 @@ +.. + Copyright 2010-2011 United States Government as represented by the + Administrator of the National Aeronautics and Space Administration. + All Rights Reserved. + + 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. + +Contributing Documentation to Cinder +==================================== + +Starting with the Pike release, Cinder's documentation has been moved from +the openstack-manuals repository to the ``docs`` directory in the Cinder +repository. This makes it even more important that Cinder add and +maintain good documentation. + +.. note:: + + Documentation for python-cinderclient and os-brick has undergone the + same transition. The information here can be applied for those + projects as well. + +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 Cinder'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 cinder.conf.sample are generated and put into ``doc/soure/_static``. + * All of Cinder's ``.py`` files are processed and the docstrings are used to + generate the files under ``doc/source/contributor/api`` + +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-cinder-docs-ubuntu-xenial``! + +Once a patch is approved it is immediately released to the docs.openstack.org +website and can be seen under Cinder's Documentation Page at +https://docs.openstack.org/cinder/latest . When a new release is cut a +snapshot of that documentation will be kept at +https://docs.openstack.org/cinder/ . Changes from master can be +backported to previous branches if necessary. + + +Doc Directory Structure +----------------------- +The main location for Cinder's documentation is the ``doc/source`` directory. +The top level index file that is seen at +`https://docs.openstack/org/cinder/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 + ../reference/README + ../user/README + +.. _https://docs.openstack/org/cinder/latest: https://docs.openstack/org/cinder/latest + diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 8b4c98be041..1c636480686 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -18,8 +18,9 @@ Contributor Guide ================= -In this section you will find information on Cinder's lower level programming -APIs. +In this section you will find information on how to contribute to Cinder. +Content includes architectural overviews, tips and tricks for setting up a +development environment, and information on Cinder's lower level programming APIs, Programming HowTos and Tutorials @@ -42,6 +43,13 @@ Programming HowTos and Tutorials rolling.upgrades groups +Documentation Contribution +-------------------------- +.. toctree:: + :maxdepth: 2 + + documentation + Background Concepts for Cinder ------------------------------ .. toctree:: diff --git a/doc/source/install/README.rst b/doc/source/install/README.rst new file mode 100644 index 00000000000..3e62df29109 --- /dev/null +++ b/doc/source/install/README.rst @@ -0,0 +1,15 @@ +================================================== +Cinder Installation Documentation (source/install) +================================================== + +Introduction: +------------- + +This directory is intended to hold any installation documentation for Cinder. +Documentation that explains how to bring Cinder 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 +`. diff --git a/doc/source/reference/README.rst b/doc/source/reference/README.rst index fd0afd4eff8..0b0d14dc03e 100644 --- a/doc/source/reference/README.rst +++ b/doc/source/reference/README.rst @@ -1,6 +1,6 @@ -============================== -Cinder Reference Documentation -============================== +================================================= +Cinder Reference Documentation (source/reference) +================================================= Introduction: ------------- diff --git a/doc/source/user/README.rst b/doc/source/user/README.rst index 27b70598c89..0271b7d1d8a 100644 --- a/doc/source/user/README.rst +++ b/doc/source/user/README.rst @@ -1,6 +1,6 @@ -========================== -Cinder User Documentation -========================== +======================================= +Cinder User Documentation (source/user) +======================================= Introduction: -------------