From 287bc2c11941a3d97d8e4d262c9d4bff2452d0fd Mon Sep 17 00:00:00 2001 From: Diane Fleming Date: Wed, 9 Apr 2014 10:16:00 -0500 Subject: [PATCH] Update README.rst Change-Id: I69ad8a7818244c565df09327fe41018826682e7d author: diane fleming --- README.rst | 89 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 64 insertions(+), 25 deletions(-) diff --git a/README.rst b/README.rst index 211367648..9e6d79f7e 100644 --- a/README.rst +++ b/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 `_. -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 `_ 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 `_. - 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 `_. + +- 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 `_ to learn more about the OpenStack project.