/
doc.sh
executable file
·403 lines (314 loc) · 7.62 KB
/
doc.sh
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
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
#!/usr/bin/env bash
#
# Usage:
# build/doc.sh <function name>
set -o nounset
set -o pipefail
set -o errexit
# https://oilshell.org/release/$VERSION/
# doc/
# index.html
# INSTALL.html
readonly OIL_VERSION=$(head -n 1 oil-version.txt)
export OIL_VERSION # for quick_ref.py
THIS_DIR=$(readlink -f $(dirname $0))
readonly THIS_DIR
REPO_ROOT=$(cd $THIS_DIR/.. && pwd)
readonly REPO_ROOT
log() {
echo "$@" 1>&2
}
#
# Deps (similar to doctools/cmark.sh and build/codegen.sh)
#
readonly MANDOC_DIR='_deps/mdocml-1.14.1'
download-mandoc() {
mkdir -p _deps
wget --no-clobber --directory _deps \
https://mandoc.bsd.lv/snapshots/mdocml-1.14.1.tar.gz
}
build-mandoc() {
cd $MANDOC_DIR
./configure
make
}
mandoc() {
$MANDOC_DIR/mandoc "$@"
}
_build-timestamp() {
echo '<hr/>'
echo "<i>Generated on $(date)</i>"
}
# Places version is used
#
# - in --version
# - in URL for every page? inside the binary
# - in titles for index, install, osh-quick-ref TOC, etc.
# - in deployment script
# Run with environment variable
_make-help() {
PYTHONPATH=. doctools/make_help.py "$@"
}
cmark() {
# h2 and h3 are shown in TOC. The blog uses "legacy" h3 and h4.
PYTHONPATH=. doctools/cmark.py --toc-tag h2 --toc-tag h3 --toc-pretty-href "$@"
}
readonly MARKDOWN_DOCS=(
# Help index has its own rendering
# polished
getting-started
known-differences
errors
errexit
json
simple-word-eval
quirks
warts
variables
eggex
deprecations
qsn
doc-toolchain
doc-plugins
future
idioms
shell-idioms
oil-language-faq
qtt
language-influences
oil-vs-python
oil-vs-shell
syntactic-concepts
syntax-feelings
# needs polish
# Note: docs about the Oil language are prefixed 'oil-'.
# data-model and command-vs-expression-mode span both OSH and Oil.
index
what-is-oil
project-tour
oil-language-tour
options
oil-keywords
oil-builtins
command-vs-expression-mode
command-language
expression-language
word-language
oil-special-vars
proc-block-func
io-builtins
unicode
framing
xtrace
headless
completion
strings
modules
# Internal stuff
variable-scope
interpreter-state
process-model
architecture-notes
parser-architecture
toil
)
readonly TIMESTAMP=$(date)
split-and-render() {
local src=${1:-doc/known-differences.md}
local name=$(basename $src .md)
local out=${2:-_release/VERSION/doc/$name.html}
local prefix=_tmp/doc/$name
# Also add could add css_files. The one in the file takes precedence always?
# css_files: a space-separated list
# all_docs_url: so we link from doc/foo.html -> doc/
doctools/split_doc.py \
-v build_timestamp="$TIMESTAMP" \
-v oil_version="$OIL_VERSION" \
-v css_files='../web/base.css ../web/manual.css ../web/toc.css ../web/language.css ../web/code.css' \
-v all_docs_url='.' \
-v repo_url="$src" \
$src $prefix
#ls -l _tmp/doc
#head _tmp/doc/*
#return
local code_out=_tmp/code-blocks/$name.txt
cmark --code-block-output $code_out ${prefix}_meta.json ${prefix}_content.md > $out
log "$prefix -> (doctools/cmark) -> $out"
}
# Special case for README
# Do NOT split because we don't want front matter in the markdown source.
render-only() {
local src=${1:-README.md}
local css_files=${2:-'../web/manual.css ../web/toc.css'}
local title=${3:-'Oil Source Code'}
local name
case $src in
*.md)
name=$(basename $src .md)
;;
*.txt)
name=$(basename $src .txt)
;;
*)
name=$(basename $src)
;;
esac
local prefix=_tmp/doc/$name
local out=_release/VERSION/doc/$name.html
local meta=${prefix}_meta.json
cat >$meta <<EOF
{ "title": "$title",
"repo_url": "$src",
"css_files": "$css_files",
"all_docs_url": ".",
"build_timestamp": "$TIMESTAMP",
"oil_version": "$OIL_VERSION"
}
EOF
cmark $meta $src > $out
log "Wrote $out"
}
special() {
render-only 'README.md' '../web/base.css ../web/manual.css ../web/toc.css' 'Oil Source Code'
render-only 'INSTALL.txt' '../web/base.css ../web/install.css' 'Installing Oil'
#
split-and-render doc/release-index.md _tmp/release-index.html
}
all-markdown() {
make-dirs
# TODO: We can set repo_url here! Then we don't need it for most docs.
# split_doc.py can return {} if the doc doesn't start with ---
#for d in doc/index.md doc/known-differences.md doc/*-manual.md \
# doc/eggex.md doc/oil-options.md doc/oil-func-proc-block.md; do
for d in "${MARKDOWN_DOCS[@]}"; do
split-and-render doc/$d.md
done
special
}
# TODO: This could use some CSS.
man-page() {
local root_dir=${1:-_release/VERSION}
mandoc -T html doc/osh.1 > $root_dir/osh.1.html
ls -l $root_dir
}
# I want to ship the INSTALL file literally, so just mutate things
_sed-ext() {
sed --regexp-extended -i "$@"
}
update-src-versions() {
_sed-ext \
"s/[0-9]+\.[0-9]+\.[a-z0-9]+/$OIL_VERSION/g" \
doc/release-index.md
# we need to update tarball paths, /release/0.8.4/ URL, etc.
_sed-ext \
"s/[0-9]+\.[0-9]+\.[a-z0-9]+/$OIL_VERSION/g" INSTALL.txt
_sed-ext \
"s;/release/[0-9]+\.[0-9]+\.[a-z0-9]+/;/release/$OIL_VERSION/;g" \
doc/osh.1
}
oil-grammar() {
PYTHONPATH=. oil_lang/cmd_parse.py "$@"
}
important-source-code() {
local dest=_tmp/important-source-code
mkdir -p $dest
for rel_path in \
frontend/lexer_def.py \
_devbuild/tmp/osh-lex.re2c.h \
_devbuild/gen/osh-lex.h \
_devbuild/gen/id.h \
frontend/syntax.asdl \
oil_lang/grammar.pgen2; do
mkdir -p $dest/$(dirname $rel_path)
cp --no-target-directory -v $rel_path $dest/$rel_path
done
}
#
# Test Tools
#
split-doc-demo() {
cat > _tmp/testdoc.md <<EOF
---
title: foo
---
Title
=====
hello
EOF
doctools/split_doc.py _tmp/testdoc.md _tmp/testdoc
head _tmp/testdoc*
}
#
# Help is both markdown and text
#
readonly TMP_DIR=_tmp/doc
readonly CODE_BLOCK_DIR=_tmp/code-blocks
readonly TEXT_DIR=_devbuild/help
readonly HTML_DIR=_release/VERSION
readonly CODE_DIR=_devbuild/gen
# TODO:
# - change to sh- vs oil- prefix, e.g. for arith
help-topics() {
_make-help topics > $TEXT_DIR/osh < $HTML_DIR/doc/osh-help-topics.html
_make-help topics > $TEXT_DIR/oil < $HTML_DIR/doc/oil-help-topics.html
}
help-cards() {
### Do all cards at once
local py_out=$CODE_DIR/help_.py
# TODO: We need to re-indent <code> blocks here, etc.
_make-help cards $TEXT_DIR $py_out \
$HTML_DIR/doc/osh-help.html $HTML_DIR/doc/oil-help.html
}
tour() {
### Build the Oil Language Tour and execute code
local name=${1:-oil-language-tour}
split-and-render doc/$name.md
local work_dir=$REPO_ROOT/_tmp/code-blocks
# Files used by module example
touch $work_dir/{build,test}.sh
mkdir -p $work_dir/lib
cat >$work_dir/lib/util.oil <<EOF
log() { echo "$@" 1>&2; }
EOF
pushd $work_dir
$REPO_ROOT/bin/oil $name.txt
popd
# My own dev tools
if test -d ~/vm-shared; then
local path=_release/VERSION/doc/$name.html
cp -v $path ~/vm-shared/$path
fi
}
one() {
### Iterate on one doc quickly
local doc=${1:-doc/oil-vs-python.md}
split-and-render $doc
if test -d ~/vm-shared; then
local out="${doc%.md}.html"
local path=_release/VERSION/$out
cp -v $path ~/vm-shared/$path
fi
}
make-dirs() {
mkdir -p $TMP_DIR $CODE_BLOCK_DIR $TEXT_DIR $HTML_DIR/doc
}
all-help() {
### Build HTML and text help, which depends on libcmark.so
log "Removing $TEXT_DIR/*"
rm -f $TEXT_DIR/*
make-dirs
split-and-render doc/oil-help-topics.md
split-and-render doc/oil-help.md
split-and-render doc/osh-help-topics.md
split-and-render doc/osh-help.md
#help-index-cards
help-topics
help-cards
# Better sorting
#LANG=C ls -l $TEXT_DIR
}
run-for-release() {
all-markdown
all-help
}
"$@"