1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
#!/usr/bin/env bash
# Usage: write-user-docs [FILES]
#
# This script writes/updates a tool's user documentation. First, pod2rst
# is called to convert the file's POD to RST. Then sphinx-build is called
# to convert the RST to HTML.
#
# RST files are written to docs/user/<tool>.rst, and HTML files are written
# to docs/user/html/<tool>.html.
#
# If no file are specified on the command line, then only the sections from
# docs/percona-toolkit.pod are written.
#
# If the env variable PERCONA_TOOLKIT_BRANCH is not set, then this script
# must be called from a directory in a branch.
#
# To rewrite all user docs from scratch:
# rm -rf docs/user/*
# util/write-user-docs bin/*
#
# Exits 0 on success, else 1 on warnings and errors.
# ############################################################################
# Standard startup, find the branch's root directory
# ############################################################################
exit_status=0
die() {
echo "$1" >&2
exit 1
}
warn() {
echo "$1" >&2
exit_status=1
}
cwd=$PWD
if [ -n "$PERCONA_TOOLKIT_BRANCH" ]; then
BRANCH=$PERCONA_TOOLKIT_BRANCH
cd $BRANCH
else
while [ ! -f Makefile.PL ] && [ $(pwd) != "/" ]; do
cd ..
done
if [ ! -f Makefile.PL ]; then
die "Cannot find the root directory of the Percona Toolkit branch"
exit 1
fi
BRANCH=`pwd`
fi
cd $cwd
# ############################################################################
# Paths
# ############################################################################
DOCS=$BRANCH/docs
RST=$DOCS/user
HTML=$RST/html
CONFIG=$BRANCH/config/sphinx-build
# ############################################################################
# Subroutines
# ############################################################################
write_rst() {
local file="$1"
if [ ! -f $file ]; then
warn "$file does not exist"
return
fi
local tool=$(basename $file)
cat $file | pod2rst --title=$tool > $RST/$tool.rst
exit_status=$(( exit_status | $? ))
echo "Wrote $RST/$tool.rst"
}
write_index() {
declare -a section_filenames
local i=0
sections=$(grep '^=head1' $DOCS/percona-toolkit.pod | grep -v "NAME" | sed -e 's/=head1 //' -e 's/ /_/g')
for section in $sections; do
header=$(echo $section | sed -e 's/_/ /g')
if [ $section = "DESCRIPTION" ]; then
filename="index"
else
filename=$(echo $section | sed -e 's/,//g' | tr "[:upper:]" "[:lower:]");
section_filenames[$i]=$filename
i=$(($i + 1))
fi
$BRANCH/util/extract-text $DOCS/percona-toolkit.pod "^=head1 $header" "^=head1|=cut" > /tmp/$filename.pod
if [ $section = "DESCRIPTION" ]; then
sed -i.bak -e 's/DESCRIPTION/Percona Toolkit Documentation/' /tmp/$filename.pod
fi
cat /tmp/$filename.pod | pod2rst | sed -e 's/.. highlight:: perl//g' > /tmp/$filename.tmp
cat -s /tmp/$filename.tmp > $RST/$filename.rst
rm /tmp/$filename.pod
rm /tmp/$filename.tmp
echo "Wrote $RST/$filename.rst"
done
echo ".. toctree::" >> $RST/index.rst
echo " :maxdepth: 2" >> $RST/index.rst
echo >> $RST/index.rst
for section_filename in "${section_filenames[@]}"; do
echo " $section_filename" >> $RST/index.rst
done
echo " release_notes" >> $RST/index.rst
echo ".. toctree::" >> $RST/tools.rst
echo " :hidden:" >> $RST/tools.rst
echo >> $RST/tools.rst
local tools=$(grep '^pt-' $RST/tools.rst)
for tool in $tools; do
echo " $tool" >> $RST/tools.rst
done
sed -e 's/^\(pt-.*\)/:doc:`\1`/g' -i.bak $RST/tools.rst
rm $RST/*.bak
}
# ############################################################################
# Script starts here
# ############################################################################
WRITE=${WRITE:-1}
if [ $WRITE -eq 1 ]; then
if [ $# -gt 0 ]; then
for tool; do
write_rst $tool
done
fi
if [ ! -f "$RST/index.rst" ] || [ "$DOCS/percona-toolkit.pod" -nt "$RST/index.rst" ]; then
write_index
fi
if [ ! -f "$RST/release_notes.rst" ] || [ "$DOCS/release_notes.rst" -nt "$RST/release_notes.rst" ]; then
cp $DOCS/release_notes.rst $RST/
echo "Wrote $RST/release_notes.rst"
fi
fi
BUILD=${BUILD:-1}
if [ $BUILD -eq 1 ]; then
# -W treats warnings as errors; remove it to ignore warnings if you must.
sphinx-build -N -W -c $CONFIG -b html $RST $HTML
exit_status=$(( exit_status | $? ))
fi
exit $exit_status
|