Adds documentation for building the v3 API docs

Change-Id: Ie844fce10d15b7b0e0052b85996f742b8f118d84

.gitignore

@@ -1 +1,2 @@
 *.swp
+openstack-identity-api/v3/identity-api-v3.xml

README.rst

@@ -1,12 +1,26 @@
 This repository contains the RESTful API information for the OpenStack Identity Service, also known as the Keystone project. The Keystone project provides authentication for OpenStack services, with plans to also provide authorization.
 
-Building
-========
+Building v2.0 Docs
+==================
 Build these docs using the same procedure as documented for the `openstack-manuals` project: https://github.com/openstack/openstack-manuals
 
 In short, with Maven 3::
 
-    cd openstack-identity-api
+    cd openstack-identity-api/v2.0
+    mvn clean generate-sources
+
+Building v3 Docs
+================
+The v3 docs require an extra proprocessing to convert the Markdown source into the DocBook format required by the Maven build process. A few extra tools are required for this preprocessing step.
+
+Installing conversion tools on Ubuntu::
+
+    apt-get install pandoc xslt-proc docbook5-xml
+
+To build the docs:
+
+    cd openstack-identity-api/v3
+    ./preprocess.sh
     mvn clean generate-sources
 
 Contributing

openstack-identity-api/v3/preprocess.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+
+# Converts the Markdown source into DocBook format suitable for using
+# in the Maven build process.
+#
+# Adapted from:
+#   https://wiki.openstack.org/wiki/Documentation/Builds#Markdown_and_DocBook
+
+SOURCES=`ls src/markdown/*.md`
+FILENAME=identity-api-v3
+DIRPATH=.
+
+XSL=/usr/share/xml/docbook/stylesheet/docbook5/db4-upgrade.xsl
+
+pandoc -f markdown -t docbook -s $SOURCES | \
+    xsltproc -o - $XSL - | \
+    xmllint --format -| \
+    sed -e "s,<article,<chapter xml:id=\"$FILENAME\"," | \
+    sed -e 's,</article>,</chapter>,' > ${DIRPATH}/$FILENAME.xml