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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
#! /bin/sh
t=__wt.$$
trap 'rm -f $t /tmp/__doxy' 0 1 2 3 13 15
# Skip this when building release packages: docs are built separately
test -n "$WT_RELEASE_BUILD" && exit 0
# We require doxygen which may not be installed.
type doxygen > /dev/null 2>&1 || {
echo 'skipped: doxygen not found'
exit 0
}
. ../RELEASE_INFO
e=0
changelog()
{
# convert the top-level NEWS file into a change log page in the docs
(echo "WiredTiger Change Log"
echo "====================="
echo
sed -e 's, \([0-9a-f]\{7\}\) , [\1](https://github.com/wiredtiger/wiredtiger/commit/\1) ,g' \
-e 's,\(\(WT\|SERVER\)-[0-9]*\),[\1](https://jira.mongodb.org/browse/\1),g' ../NEWS) > ../src/docs/changelog.md
}
wtperf_config()
{
# The Linux ed command writes line numbers to stderr, redirect both
# stdout and stderr to keep things quiet.
cc -o /tmp/__doxy ../bench/wtperf/doxy.c &&
(echo '/START_AUTO_GENERATED_WTPERF_CONFIGURATION/+3,/STOP_AUTO_GENERATED_WTPERF_CONFIGURATION/-1d'
echo 'i'
echo ''
echo '.'
echo ".r !/tmp/__doxy"
echo 'a'
echo ''
echo '.'
echo 'w'
echo 'q') | ed ../src/docs/wtperf.dox 1>/dev/null 2>/dev/null &&
rm -f /tmp/__doxy
}
structurechk()
{
# @page names should match the source file name
(cd ../src/docs &&
grep @page *.dox |
sed 's/\([^:]*\)\.dox:.*@page \([^ ]*\) .*/\1 \2/g' |
sed 's/-/_/g' | awk '{ if ($1 != $2) { print $1 " != " $2; } }') > $t
test -s $t && {
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
echo "@page references don't match source file names"
sed -e 's/^/ /' < $t
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
e=1
}
# sections are a global name space for doxygen, and must be uniquely
# named or you can get the wrong results. For example, if you have
# "@section foo ABC" and "@section foo DEF", they will both appear as
# "ABC" or "DEF".
(cd ../src/docs &&
sed -n 's/@section \([^ ]*\)/\1/p' *.dox | sort | uniq -d) > $t
test -s $t && {
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
echo '@section references that are not uniquely named'
sed -e 's/^/ /' < $t
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
e=1
}
# we want a simple tree structure for navigation, otherwise
# clicking in the navigation tree can jump to a different point in
# the tree
(cd ../src/docs &&
sed -n 's/@subpage \([^ ]*\)/\1/p' *.dox | sort | uniq -d) > $t
test -s $t && {
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
echo 'multiple @subpage references for the same page'
sed -e 's/^/ /' < $t
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
e=1
}
}
spellchk()
{
# If aspell has been installed, run a spell check.
type aspell > /dev/null 2>&1 || return
(cd ../src/docs &&
cat *.dox | aspell --lang=en --personal=./spell.ok list) |
sort -u > $t
test -s $t && {
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
echo 'Documentation spelling notes'
echo 'Update src/docs/spell.ok to remove warnings.'
sed -e 's/^/ /' < $t
echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-="
e=1
}
}
valid_build()
{
# Complain if there are pages we don't reference directly.
sed -n '/<table.*directory/,/\/table/p' < ../docs/pages.html | \
grep href > /dev/null && {
echo 'Unreferenced page: see docs/pages.html for the list.'
e=1
}
classf=`ls ../docs/struct___* 2>/dev/null`
for c in $classf; do
echo "$c: Add class to PREDEFINED in src/docs/Doxyfile, then remove docs/*.{html,js} and rebuild"
done
}
build()
{
# Build from scratch on demand.
[ "$1" -eq 0 ] || (cd .. && rm -rf docs && mkdir docs)
# Run doxygen to generate warnings for the base HTML documentation.
#
# We omit Python because warnings are expected there (the code generated
# by swig does not have named arguments, but we want to document them
# as if they do.
(cd ../src/docs &&
(eval cat Doxyfile $filter ; cat <<EOF
QUIET=YES
EOF
) | doxygen -
test -s doxygen.log && cat doxygen.log) > $t 2>&1
test -s $t && {
cat $t
e=1
}
# Add optional extras
EXTRAS="../lang/java/src/com/wiredtiger/db ../lang/python/wiredtiger.py"
EXTRA_INPUT=""
for f in $EXTRAS ; do
[ -e "$f" ] && EXTRA_INPUT="$EXTRA_INPUT ../$f"
done
# Run again to generate the full doc set with Python and Java.
[ "$additional_languages" -eq 1 ] && [ "x$EXTRA_INPUT" != "x" ] && (
cd ../src/docs &&
(eval cat Doxyfile $filter ; cat <<EOF
QUIET=YES
INPUT+=$EXTRA_INPUT
EOF
) | doxygen -)
# Fix up bad links doxygen generates in navtree.js
(cd ../docs &&
sed -i~ -e 's,/\.html,/,' -e 's,\.html\.html,.html,' navtree.js &&
rm -f navtree.js~)
# Fixup the man pages generated by Doxygen. We want the command line
# documentation to be the main man page, but also install a man page
# for the WiredTiger header into the library section.
[ "$additional_languages" -eq 1 ] &&
(cd ../docs && mkdir -p man/man1 &&
mv man/man3/command_line.3 man/man1/wt.1 &&
sed -i~ -e 's/command_line/wt/g' man/man1/wt.1 &&
sed -i~ -e 's/Version Version/Version/g' man/man1/wt.1 &&
rm -f man/man1/wt.1~ &&
mv man/man3/basic_api.3 man/ && rm -f man/man3/* &&
mv man/basic_api.3 man/man3/wiredtiger.3 &&
sed -i~ -e 's/basic_api/WiredTiger/g' man/man3/wiredtiger.3 &&
sed -i~ -e 's/Version Version/Version/g' man/man3/wiredtiger.3 &&
rm -f man/man3/wiredtiger.3~)
}
clean=0
additional_languages=1
filter="|sed '/PROJECT_NUMBER/s,=.*,=\"Version $WIREDTIGER_VERSION\",'"
while :
do case "$1" in
-a) # Build from scratch
clean=1
shift;;
-l) # Generate the top-level landing page in ../docs/top
filter="$filter| sed '/GENERATE_MAN/s,=.*,=NO,';"
filter="$filter cat top/Doxyfile"
additional_languages=0
shift;;
-p) # Generate PDFs
filter="$filter| sed '/GENERATE_LATEX/s,=.*,=YES,'"
shift;;
-t) # Include the TODO list
filter="$filter| sed '/GENERATE_TODOLIST/s,=.*,=YES,'"
shift;;
*)
break;;
esac
done
# Generate the change log
changelog
# Generate the list of wtperf configuration options.
wtperf_config
# Spell and structure check the documentation.
spellchk
structurechk
# Build the documentation.
build $clean
# Any post-build validity checks we want to make.
valid_build
exit $e
|
