openstack/openstack-manuals
Code Issues Proposed changes

Rewrite README for RST guides

Browse Source 
At now, all guide are in RST format, except for glossary.
To reflect the situation, rewrite README.
Also, refer contributor guide for details.

Change-Id: If3c6434e582912edf226e3484f289355de632f19
This commit is contained in:
KATO Tomoyuki 2016-01-16 09:55:49 +09:00
parent 21da3a43ee
commit 0b28e35206
1 changed files with 33 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
README.rst
View File

@ -3,8 +3,8 @@ OpenStack Manuals
This repository contains documentation for the OpenStack project.
For more details, see the `OpenStack Documentation wiki page
<http://wiki.openstack.org/Documentation>`_.
For more details, see the `OpenStack Documentation Contributor
Guide <http://docs.openstack.org/contributor-guide/>`_.
It includes these manuals:
@ -21,12 +21,34 @@ It includes these manuals:
In addition to the guides, this repository contains:
* docs.openstack.org: ``www``
* docs.openstack.org contents: ``www``
Building
========
Various manuals are in subdirectories of the ``doc/`` directory.
Guides
------
Various guides are in the RST format. You can use tox to prepare
virtual environment and build all RST based guides::
tox -e docs
You can also build a specific guide.
For example, to build *OpenStack End User Guide*, use the following command::
tox -e build -- user-guide
You can find the root of the generated HTML documentation at::
doc/user-guide/build/html/index.html
Glossary
--------
Prerequisites
=============
`Apache Maven <http://maven.apache.org/>`_ must be installed to build the
documentation.
glossary.
To install Maven 3 for Ubuntu 12.04 and later, and Debian wheezy and later::
@ -41,48 +63,21 @@ On openSUSE 13.1 and later::
zypper ar http://download.opensuse.org/repositories/devel:/tools:/building/openSUSE_13.1/devel:tools:building.repo
zypper install maven
Building
========
The different manuals are in subdirectories of the
``openstack-manuals/doc/`` directory.
To build the glossary, move to ``doc/glossary``,
then run the ``mvn`` command in that directory::
DocBook guides
--------------
For example, the root directory of the *OpenStack Command-Line Interface Reference*
is ``openstack-manuals/doc/cli-reference``.
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 openstack-manuals/doc/cli-reference/
cd doc/glossary
mvn clean generate-sources
The generated PDF documentation file is::
openstack-manuals/doc/cli-reference/target/docbkx/webhelp/cli-reference/cli-reference.pdf
doc/glossary/target/docbkx/webhelp/glossary/glossary.pdf
The root of the generated HTML documentation is::
openstack-manuals/doc/cli-reference/target/docbkx/webhelp/cli-reference/content/index.html
doc/glossary/target/docbkx/webhelp/glossary/content/index.html
RST guides
----------
Then, you can see some guides written in the RST format, so we can't use mvn command.
You can use tox to prepare virtual environment and build all RST based guides::
tox -e docs
You can also build a specific guide.
For example, to build *OpenStack End User Guide*, use the following command::
tox -e build -- user-guide
You can find the root of the generated HTML documentation at::
openstack-manuals/doc/user-guide/build/html/index.html
Testing of changes and building of the manual
=============================================