From cd5b8e13859a10d836b35c942dd3b785ae09f62c Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Wed, 8 Jun 2016 17:09:08 -0500 Subject: [PATCH] Updates to README for current state - Remove Maven build info - Add an indicator that api-ref directory will not accept changes - Remove API reference mentions Change-Id: Ieacc5ca3fa8342b4417465e25ff4ae0112083936 --- README.rst | 96 +++++++++++++----------------------------------------- 1 file changed, 22 insertions(+), 74 deletions(-) diff --git a/README.rst b/README.rst index 5190f009f..ac49af17d 100644 --- a/README.rst +++ b/README.rst @@ -8,34 +8,39 @@ For details, see the which includes these pages and PDFs: * API Quick Start - * API Complete Reference (web pages) - * API Reference PDFs * API Guide (in progress) In addition to these documents, this repository contains: - * developer.openstack.org: ``www`` + * Landing page for developer.openstack.org: ``www`` * Writing your first OpenStack application tutorial (in progress): ``firstapp`` +The files in the ``api-ref`` directory cannot be changed because they are +moving to project repositories. + +To complete code reviews in this repository, use the standard OpenStack Gerrit +`workflow `_ . For details, see +`Gerrit Workflow `_. + Prerequisites ============= -To build the documentation, you must install `Apache Maven `_. - -To install Maven 3 for Ubuntu 12.04 or later or Debian 7 ("wheezy") or later:: - - apt-get install maven - -On Fedora 20 or later:: - - yum install maven - -To run tests, you must install `Python Tox `_. +To build the documentation locally, you must install Python and `Python Tox `_. To install Tox for Ubuntu 14.04 or later:: apt-get install python-tox python-dev libxml2-dev libxslt1-dev +To build all the documentation after installing Python and Tox:: + + tox -e docs + +To build an individual document, such as the API Quick Start:: + + tox -e api-quick-start + +The locally-built output files are found in a ``publish-docs`` directory. + "Writing your First OpenStack Application" tutorial ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -61,61 +66,8 @@ On Mac OSX with Homebrew installed:: Build and update API docs ========================= -To complete code reviews in this repository, use the standard OpenStack Gerrit -`workflow `_ . For details, see -`Gerrit Workflow `_. - -To build and update the API documents: - -#. Open a Terminal window. - -#. Change into a directory where you want to clone api-site. - -#. Run this command to clone openstack/api-site:: - - git clone https://git.openstack.org/openstack/api-site - -#. CD into the api-site directory. - -#. Run these commands to ensure that you have the latest changes:: - - git remote update - git checkout master - git pull origin master - -#. To check out a new branch:: - - git checkout -b "*my_branch*" - - Otherwise, to check out 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 - +Refer to the `OpenStack Documentation Contributor Guide ` for more +information. Run tests ========= @@ -128,14 +80,11 @@ To run individual tests: * ``tox -e checkniceness`` - Niceness tests * ``tox -e checksyntax`` - Syntax checks * ``tox -e checkdeletions`` - Verifies that no deleted files are referenced - * ``tox -e checkbuild`` - Builds the manual + * ``tox -e checkbuild`` - Builds all of the documents in this repository To run these tests, the Tox package uses the `OpenStack doc tools package `_. -The OpenStack doc tools require Maven for the build check. - - Contribute ========== @@ -160,7 +109,6 @@ File bugs on Launchpad and not through GitHub: https://bugs.launchpad.net/openstack-api-site/ - Install =======