← Back to branch summary

~akiban-technologies/akiban-persistit/trunk

« back to all changes in this revision

Viewing changes to doc/build/build-doc.sh

merge nwilliams: Minor formatting, wording, and link clean-ups for the final docs.

https://code.launchpad.net/~nwilliams/akiban-persistit/minor-doc-cleanup-for-oe/+merge/108224

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/build/build-doc.sh
1
 
#/bin/sh
 
1
#!/bin/bash
2
2
#
3
3
# Copyright © 2011-2012 Akiban Technologies, Inc.  All rights reserved.
4
4
# 
19
19
# information, see www.akiban.com or contact licensing@akiban.com.
20
20
# 
21
21
 
22
 
# ---------------------
23
22
#
24
23
# Builds the Akiban Persistit doc set.  Currently this process is based on
25
 
# the asciidoc tool (http://www.methods.co.nz/asciidoc/).
 
24
# the Sphinx tool (http://sphinx.pocoo.org/).
26
25
#
27
26
# Here are the steps:
28
 
# 1. Run a Java program AsciiDocPrep to prepare a text asciidoc file.
29
 
#    Among other things, AsciiDocPrep fills in JavaDoc hyperlinks.
30
 
# 2. Run asciidoc to generate an html file.
31
 
# 3. Use sed to replace some characters.  Turns out asciidoc doesn't like
32
 
#    to link to URLs having spaces, so AsciDocPrep replaces those spaces
33
 
#    with the "`" character.  This step converts those back to spaces.
34
 
#
35
 
# Run this script from the root of the persistit source directory. This
36
 
# script writes changes only into a directory /tmp/akiban-persistit-doc.
37
 
# The end-product files, user_guide.html and user_guide.xml are written
38
 
# there.
39
 
#
40
 
rm -rf ../../target/sphinx/source
41
 
mkdir -p ../../target/sphinx/source
42
 
mkdir -p ../../target/sphinx/classes
43
 
mkdir -p ../../target/sphinx/html
44
 
mkdir -p ../../target/sphinx/text
45
 
 
46
 
cp ../index.rst ../../target/sphinx/source
47
 
cp ../conf.py ../../target/sphinx/source
 
27
# 1. Run a Java program SphinxDocPrep to prepare a text rst file.
 
28
#    Among other things, SphinxDocPrep fills in JavaDoc hyperlinks.
 
29
# 2. Run sphinx-build to generate html files.
 
30
# 3. Use fold and sed to specially prepare an extra plain text file
 
31
#    for the release notes.
 
32
#
 
33
# Run this script from the doc/build/ directory of the persistit source
 
34
# tree. This script writes all output into the ../../target/sphinx 
 
35
# directory.
 
36
#
 
37
 
 
38
APIDOC_INDEX="../../target/site/apidocs/index-all.html"
 
39
APIDOC_URL=${APIDOC_URL:-"http://www.akiban.com/ak-docs/admin/persistit-api"}
 
40
DOCPREP_CLASS="SphinxDocPrep"
 
41
DOCPREP_CLASSPATH="../../target/sphinx/classes:../../target/classes"
 
42
 
 
43
DOC_SOURCE_PATH=".."
 
44
DOC_TARGET_PATH="../../target/sphinx/source"
 
45
DOC_FINAL_PATH="../../target/sphinx/html"
 
46
DOC_FILES="\
 
47
    ReleaseNotes.rst\
 
48
    BasicAPI.rst\
 
49
    Configuration.rst\
 
50
    GettingStarted.rst\
 
51
    Management.rst\
 
52
    Miscellaneous.rst\
 
53
    PhysicalStorage.rst\
 
54
    Security.rst\
 
55
    Serialization.rst\
 
56
    Transactions.rst\
 
57
"
 
58
 
 
59
rm -rf ../../target/sphinx/
 
60
mkdir -p ../../target/sphinx/{classes,html,source/_static,text}
 
61
 
 
62
cp ../index.rst ../conf.py ../../target/sphinx/source
48
63
 
49
64
javac -d ../../target/sphinx/classes -cp ../../target/classes/ src/*.java
50
65
 
51
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../ReleaseNotes.rst out=../../target/sphinx/source/ReleaseNotes.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
52
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../BasicAPI.rst out=../../target/sphinx/source/BasicAPI.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
53
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../Configuration.rst out=../../target/sphinx/source/Configuration.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
54
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../GettingStarted.rst out=../../target/sphinx/source/GettingStarted.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
55
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../Management.rst out=../../target/sphinx/source/Management.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
56
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../Miscellaneous.rst out=../../target/sphinx/source/Miscellaneous.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
57
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../PhysicalStorage.rst out=../../target/sphinx/source/PhysicalStorage.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
58
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../Security.rst out=../../target/sphinx/source/Security.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
59
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../Serialization.rst out=../../target/sphinx/source/Serialization.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
60
 
java -cp ../../target/sphinx/classes:../../target/classes SphinxDocPrep in=../Transactions.rst out=../../target/sphinx/source/Transactions.rst base=http://www.akiban.com/ak-docs/admin/persistit/apidocs index=../../target/site/apidocs/index-all.html
61
 
 
62
 
sphinx-build -a  ../../target/sphinx/source ../../target/sphinx/html
63
 
 
64
 
fold -s ../../target/sphinx/source/ReleaseNotes.rst | sed 's/``//g' | sed 's/\.\. note:/NOTE/' | sed 's/::/:/' > ../../target/sphinx/text/ReleaseNotes
 
66
for f in $DOC_FILES; do
 
67
    java -cp "$DOCPREP_CLASSPATH" "$DOCPREP_CLASS" in="${DOC_SOURCE_PATH}/${f}" out="${DOC_TARGET_PATH}/${f}" base="$APIDOC_URL" index="$APIDOC_INDEX"
 
68
done
 
69
 
 
70
sphinx-build -a "$DOC_TARGET_PATH" "$DOC_FINAL_PATH"
 
71
 
 
72
fold -s "${DOC_TARGET_PATH}/ReleaseNotes.rst" | sed 's/``//g' | sed 's/\.\. note:/NOTE/' | sed 's/::/:/' > ../../target/sphinx/text/ReleaseNotes
65
73