168 lines
4.6 KiB
ReStructuredText
168 lines
4.6 KiB
ReStructuredText
API-Site repository
|
|
+++++++++++++++++++
|
|
|
|
This repository contains documentation for the OpenStack project.
|
|
|
|
For details, see the
|
|
`OpenStack Documentation wiki page <http://wiki.openstack.org/Documentation>`_,
|
|
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``
|
|
* Writing your first OpenStack application tutorial (in progress): ``firstapp``
|
|
|
|
Prerequisites
|
|
=============
|
|
|
|
To build the documentation, you must install `Apache Maven <http://maven.apache.org/>`_.
|
|
|
|
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 <https://tox.readthedocs.org/>`_.
|
|
|
|
To install Tox for Ubuntu 14.04 or later::
|
|
|
|
apt-get install python-tox python-dev libxml2-dev libxslt1-dev
|
|
|
|
"Writing your First OpenStack Application" tutorial
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To build the "Writing your first OpenStack application" tutorial, you must
|
|
install `Graphviz <http://www.graphviz.org/>`_.
|
|
|
|
To install Graphviz for Ubuntu 12.04 or later or Debian 7 ("wheezy") or later::
|
|
|
|
apt-get install graphviz
|
|
|
|
On Fedora 22 and later::
|
|
|
|
dnf install graphviz
|
|
|
|
On openSUSE::
|
|
|
|
zypper install graphviz
|
|
|
|
On Mac OSX with Homebrew installed::
|
|
|
|
brew install graphviz
|
|
|
|
Build and update API docs
|
|
=========================
|
|
|
|
To complete code reviews in this repository, use the standard OpenStack Gerrit
|
|
`workflow <https://review.openstack.org>`_ . For details, see
|
|
`Gerrit Workflow <http://docs.openstack.org/infra/manual/developers.html#development-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 <http://docs.openstack.org/infra/manual/developers.html#development-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
|
|
=========
|
|
|
|
To use the same tests that are used as part of our Jenkins gating jobs,
|
|
install the Python tox package and run ``tox`` from the top-level directory.
|
|
|
|
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
|
|
|
|
To run these tests, the Tox package uses the
|
|
`OpenStack doc tools package <https://github.com/openstack/openstack-doc-tools>`_.
|
|
|
|
The OpenStack doc tools require Maven for the build check.
|
|
|
|
|
|
Contribute
|
|
==========
|
|
|
|
Our community welcomes everyone who is interested in open source cloud
|
|
computing and encourages you to join the `OpenStack Foundation <http://www.openstack.org/join>`_.
|
|
|
|
The best way to get involved with the community is to talk with others online
|
|
or at a meetup and offer contributions through our processes, the
|
|
`OpenStack wiki <http://wiki.openstack.org>`_, blogs, or on IRC at ``#openstack`` on
|
|
``irc.freenode.net``.
|
|
|
|
We welcome all types of contributions, from blueprint designs to documentation
|
|
to testing to deployment scripts.
|
|
|
|
To contribute to the documents, see
|
|
`Documentation HowTo <https://wiki.openstack.org/wiki/Documentation/HowTo>`_.
|
|
|
|
Bugs
|
|
====
|
|
|
|
File bugs on Launchpad and not through GitHub:
|
|
|
|
https://bugs.launchpad.net/openstack-api-site/
|
|
|
|
|
|
Install
|
|
=======
|
|
|
|
To learn more about the OpenStack project, see `OpenStack <http://www.openstack.org/>`_.
|