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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
#!/usr/bin/env bash
#set -x
# Usage: write-user-docs [TOOLS]
#
# This script writes/updates the user documentation. User docs come from
# three places: each tool's POD (pod2rst is used to convert their POD docs
# to RST), static .rst file (docs/*.rst), and most head1 sections in
# docs/percona-toolkit.pod (also converted writh pod2rst; this file is needed
# in .pod form because it's used to make the percona-toolkit man page).
#
# Run this script from any directory in the branch whose user docs you want
# to build. For example, to build user docs in the 2.0 branch:
# $ cd ~dev/perona-toolkit/2.0
# $ util/write-user-docs
# Unlike other scripts, this one does *not* use PERCONA_TOOLKIT_BRANCH.
#
# After all the RST files have been written, this script runs `make html'
# in config/sphinx-build/ (which has a Makefile) to build the online HTML
# docs, which are saved in docs/user/html.
#
# If no tools are specified on the command line, then docs for bin/* are
# written (plus all the extra sections).
#
# To rewrite all user docs from scratch:
# rm -rf docs/user/*
# util/write-user-docs
#
# 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
while [ ! -f Makefile.PL ] && [ $(pwd) != "/" ]; do
cd ..
done
if [ ! -f Makefile.PL ]; then
die "Cannot find the root directory of the Percona Toolkit branch"
fi
BRANCH=`pwd`
cd $cwd
# ############################################################################
# Paths
# ############################################################################
DOCS_DIR=$BRANCH/docs
RST_DIR=$DOCS_DIR/user
# ############################################################################
# Subroutines
# ############################################################################
fix_html () {
local name="$1"
perl -MFile::Basename=basename -le '
my $f = shift;
my $tool = basename($f);
$tool =~ s/\.html//;
my $out = do { open my $fh, q{<}, $f or die "$f: $!"; local $/; <$fh> };
$out =~ s{
\Q<dt id="\E(cmdoption-$tool--)\Q">\E\s*
\Q<tt class="descname">--</tt><tt class="descclassname">\E([^<]+)
\Q</tt><a class="headerlink" href="\E[^"]+"
}{<dt id="$1$2">
<tt class="descname">--$2</tt><tt class="descclassname"></tt><a class="headerlink" href="#$1$2"}xg;
open my $fh, q{>}, $f or die "Cannot open $f for writing: $!";
print { $fh } $out;
close $fh or die "Cannot close $f: $!";
' "$RST_DIR/html/$name.html"
}
write_rst() {
local file="$1"
local tool="$(basename $1)"
if [ ! -f $file ]; then
warn "$file does not exist"
return
fi
$BRANCH/util/pod2rst-fixed.packed $file > $RST_DIR/$tool.rst
if [ $? -eq 0 ]; then
echo "Wrote $RST_DIR/$tool.rst"
else
die "Error writing $RST_DIR/$tool.rst"
fi
}
# Parse the head1 sections from percona-toolkit.pod and write them as
# individual .rst files, except the sections in the grep -Ev below.
# For example, head1 SYSTEM REQUIREMENTS becomes system_requirements.rst.
# These sections are included in index.rst.
write_sections() {
# Grep head1 sections from percona-toolkit.pod, except a few, and
# change spaces to _ so the for..do loop doesn't treat "SYS REQS"
# as two sections.
sections=$(grep '^=head1' $DOCS_DIR/percona-toolkit.pod | sed -e 's/=head1 //' -e 's/ /_/g' | grep -Ev "^NAME|DESCRIPTION|TOOLS")
for section in $sections; do
# Put spaces back in the section's name.
header=$(echo $section | sed -e 's/_/ /g')
# Convert the section name to a simple filename.
filename=$(echo $section | sed -e 's/,//g' -e 's/[()]//g' | tr "[:upper:]" "[:lower:]");
# Extract the section as POD.
local start_line=$(grep --line-number "^=head1 $header" $DOCS_DIR/percona-toolkit.pod | cut -d':' -f1)
if [ -z "$start_line" ]; then
die "Cannot find $from in $DOCS_DIR/percona-toolkit.pod"
fi
tail -n +$start_line $DOCS_DIR/percona-toolkit.pod | awk "BEGIN { getline; print \$0 } /^=head1|=cut/ { exit } { print }" > /tmp/$filename.pod
# Convert POD to RST and remove all the Perl highlight blocks.
$BRANCH/util/pod2rst-fixed.packed /tmp/$filename.pod --no-fix | sed -e 's/.. highlight:: perl//g' > /tmp/$filename.tmp
# Remove extra blank lines.
cat -s /tmp/$filename.tmp > $RST_DIR/$filename.rst
# Remove tmp files.
rm /tmp/$filename.pod
rm /tmp/$filename.tmp
echo "Wrote $RST_DIR/$filename.rst"
done
}
# ############################################################################
# Script starts here
# ############################################################################
WRITE=${WRITE:-1}
if [ $WRITE -eq 1 ]; then
if [ $# -gt 0 ]; then
for tool; do
write_rst $tool
done
else
for tool in `ls $BRANCH/bin/*`; do
write_rst $tool
done
fi
# Parse and write certain parts of percona-toolkit.pod.
write_sections
# Copy all static .rst files, like index.rst.
cp $DOCS_DIR/*.rst $RST_DIR/
echo "Copied $DOCS_DIR/*.rst to $RST_DIR"
fi
BUILD=${BUILD:-1}
if [ $BUILD -eq 1 ]; then
cd $BRANCH/config/sphinx-build
make html && make latexpdf
exit_status=$(( exit_status | $? ))
fi
if [ $# -gt 0 ]; then
for tool; do
name="$(basename $tool)"
fix_html $name
done
else
for tool in `ls $BRANCH/bin/*`; do
name="$(basename $tool)"
fix_html $name
done
fi
exit $exit_status
|
