From 8b90e507b5eccecdc94aef5733d8bd968954c84e Mon Sep 17 00:00:00 2001
From: David Stanek <dstanek@dstanek.com>
Date: Wed, 16 Oct 2013 16:01:14 +0000
Subject: [PATCH] Adds documentation for building the v3 API docs

Change-Id: Ie844fce10d15b7b0e0052b85996f742b8f118d84
---
 .gitignore                              |  1 +
 README.rst                              | 20 +++++++++++++++++---
 openstack-identity-api/v3/preprocess.sh | 19 +++++++++++++++++++
 3 files changed, 37 insertions(+), 3 deletions(-)
 create mode 100755 openstack-identity-api/v3/preprocess.sh

diff --git a/.gitignore b/.gitignore
index 1377554e..2d3ecc61 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 *.swp
+openstack-identity-api/v3/identity-api-v3.xml
diff --git a/README.rst b/README.rst
index 49e958a2..882e2609 100644
--- a/README.rst
+++ b/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
diff --git a/openstack-identity-api/v3/preprocess.sh b/openstack-identity-api/v3/preprocess.sh
new file mode 100755
index 00000000..6982237d
--- /dev/null
+++ b/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