Update README.rst

Change-Id: I69ad8a7818244c565df09327fe41018826682e7d
author: diane fleming

README.rst

@@ -1,4 +1,4 @@
-API-Site Repository
+API-Site repository
 +++++++++++++++++++
 
 This repository contains documentation for the OpenStack project.
@@ -6,18 +6,20 @@ This repository contains documentation for the OpenStack project.
 For more details, see the `OpenStack Documentation wiki page
 <http://wiki.openstack.org/Documentation>`_.
 
-It includes these manuals:
+It includes these pages and PDFs:
 
  * API Quick Start
- * API Complete Reference
+ * API Complete Reference (web pages)
+ * API Reference PDFs
+ * API Guide (in progress)
 
 In addition to these, this repository contains:
 
  * api.openstack.org: ``www``
 
-
 Prerequisites
 =============
+
 `Apache Maven <http://maven.apache.org/>`_ must be installed to build the
 documentation.
 
@@ -29,27 +31,64 @@ On Fedora 15 and later::
 
     yum install maven3
 
-Building
-========
-The manuals are in the ``api-quick-start`` and ``api-ref``
-directories.
+Build and update API docs
+=========================
 
-To build a specific guide, look for a ``pom.xml`` file within a subdirectory,
-then run the ``mvn`` command in that directory. For example::
+For more details about the Gerrit workflow, see `Gerrit Workflow <https://wiki.openstack.org/wiki/GerritWorkflow>`_.
 
-    cd api-quick-start
-    mvn clean generate-sources
+To build and updates any of the API documents:
 
-The generated PDF documentation file is::
+#. Open a Terminal window.
 
-    api-quick-start/target/docbkx/webhelp/api-quick-start-onepager-external/api-quick-start-onepager.pdf
+#. Change into a directory where you want to clone api-site.
 
-The root of the generated HTML documentation is::
+#. Run this command to clone openstack/api-site::
 
-    api-quick-start/target/docbkx/webhelp/api-quick-start-onepager-external/content/index.html
+        git clone https://github.com/openstack/api-site
 
-Testing of changes and building of the manual
-=============================================
+#. CD into the api-site directory.
+
+#. Run these commands to ensure you have the latest changes::
+
+        git remote update
+        git checkout master
+        git pull origin master
+
+#. To checkout a new branch::
+
+        git checkout -b "*my_branch*"
+
+   Otherwise, to checkout an existing review::
+
+        git review –d change-number /* where change-number is the change number of the review
+
+#. Make your changes.
+
+#. Run this command to build the docs locally::
+
+        mvn clean generate-sources
+
+#. To check in your changes, see `Gerrit Workflow <https://wiki.openstack.org/wiki/GerritWorkflow>`_.
+
+- The root of the generated HTML (API site) documentation is::
+
+        api-site/api-ref/target/docbkx/html/api-ref.html
+
+- The root of the generated API guide (in progress) is::
+
+        api-site/api-guide/target/docbkx/webhelp/api-guide/index.html
+
+- The generated PDFs for the API pages are at::
+
+        api-site/api-ref-guides/target/docbkx/pdf/*.pdf
+
+- The root of the API quick start is at::
+
+        api-site/api-quick-start/target/docbkx/webhelp/api-quick-start-onepager-external/api-quick-start-onepager.pdf
+
+
+Run tests
+=========
 
 Install the python tox package and run ``tox`` from the top-level
 directory to use the same tests that are done as part of our Jenkins
@@ -68,8 +107,8 @@ these tests. openstack-doc-tools has a requirement on maven for the
 build check.
 
 
-Contributing
-============
+Contribute
+==========
 
 Our community welcomes all people interested in open source cloud
 computing, and encourages you to join the `OpenStack Foundation
@@ -89,12 +128,12 @@ If you would like to contribute to the documents, please see the
 Bugs
 ====
 
-Bugs should be filed on Launchpad, not GitHub:
+Bugs should be filed on Launchpad, and not GitHub:
 
    https://bugs.launchpad.net/openstack-api-site/
 
 
-Installing
-==========
-Refer to http://docs.openstack.org to see where these documents are published
-and to learn more about the OpenStack project.
+Install
+=======
+
+See `OpenStack <http://www.openstack.org/>`_ to learn more about the OpenStack project.