diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d3686ec --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +# Testenvironment +.tox/ + +# Generated files +target/ diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..9cff7da --- /dev/null +++ b/README.rst @@ -0,0 +1,92 @@ +Database-API Repository ++++++++++++++++++++ + +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: + + * Database Services API Reference + +Prerequisites +============= +`Apache Maven <http://maven.apache.org/>`_ must be installed to build the +documentation. + +To install Maven 3 for Ubuntu 12.04 and later, and Debian wheezy and later:: + + apt-get install maven + +On Fedora 15 and later:: + + yum install maven3 + +Building +======== +The manuals are in the ``apidocs`` directory. + +To build a specific guide, look for a ``pom.xml`` file within a subdirectory, +then run the ``mvn`` command in that directory. For example:: + + cd apidocs + mvn clean generate-sources + +The generated PDF documentation file is:: + + apidocs/target/docbkx/webhelp/cdb-devguide/cdb-devguide-reviewer.pdf + +The root of the generated HTML documentation is:: + + apidocs/target/docbkx/webhelp/cdb-devguide/content/index.html + +Testing of changes and building of the manual +============================================= + +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 +gating jobs. + +If you like to run individual tests, run: +* ``tox -e checkniceness`` - to run the niceness tests +* ``tox -e checksyntax`` - to run syntax checks +* ``tox -e checkdeletions`` - to check that no deleted files are referenced +* ``tox -e checkbuild`` - to actually build the manual + +tox will use the `openstack-doc-tools package +<https://github.com/openstack/openstack-doc-tools>`_ for execution of +these tests. openstack-doc-tools has a requirement on maven for the +build check. + + +Contributing +============ + +Our community welcomes all people 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. + +If you would like to contribute to the documents, please see the +`Documentation HowTo <https://wiki.openstack.org/wiki/Documentation/HowTo>`_. + +Bugs +==== + +Bugs should be filed on Launchpad, 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. diff --git a/test-requirements.txt b/test-requirements.txt new file mode 100644 index 0000000..5090e85 --- /dev/null +++ b/test-requirements.txt @@ -0,0 +1 @@ +openstack-doc-tools diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..7ebe193 --- /dev/null +++ b/tox.ini @@ -0,0 +1,27 @@ +[tox] +minversion = 1.6 +envlist = checkniceness,checksyntax,checkdeletions,checkbuild +skipsdist = True + +[testenv] +setenv = + VIRTUAL_ENV={envdir} + LANG=en_US.UTF-8 + LANGUAGE=en_US:en + LC_ALL=C +deps = -r{toxinidir}/test-requirements.txt + +[testenv:venv] +commands = {posargs} + +[testenv:checkniceness] +commands = openstack-doc-test --api-site --check-niceness {posargs} + +[testenv:checksyntax] +commands = openstack-doc-test --api-site --check-syntax {posargs} + +[testenv:checkdeletions] +commands = openstack-doc-test --api-site --check-deletions {posargs} + +[testenv:checkbuild] +commands = openstack-doc-test --api-site --check-build {posargs}