From 0b28e35206413e200d4370de68f1c8456f8b7b5c Mon Sep 17 00:00:00 2001 From: KATO Tomoyuki Date: Sat, 16 Jan 2016 09:55:49 +0900 Subject: [PATCH] Rewrite README for RST guides 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 --- README.rst | 71 +++++++++++++++++++++++++----------------------------- 1 file changed, 33 insertions(+), 38 deletions(-) diff --git a/README.rst b/README.rst index dfd71102a7..80cf20e122 100644 --- a/README.rst +++ b/README.rst @@ -3,8 +3,8 @@ OpenStack Manuals This repository contains documentation for the OpenStack project. -For more details, see the `OpenStack Documentation wiki page -`_. +For more details, see the `OpenStack Documentation 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 `_ 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 =============================================