| 1 | #!/usr/bin/env bash
|
| 2 | #
|
| 3 | # Usage:
|
| 4 | # build/doc.sh <function name>
|
| 5 |
|
| 6 | set -o nounset
|
| 7 | set -o pipefail
|
| 8 | set -o errexit
|
| 9 |
|
| 10 | # https://oilshell.org/release/$VERSION/
|
| 11 | # doc/
|
| 12 | # index.html
|
| 13 | # INSTALL.html
|
| 14 | # INSTALL-old.html
|
| 15 |
|
| 16 | readonly OILS_VERSION=$(head -n 1 oils-version.txt)
|
| 17 | export OILS_VERSION # for quick_ref.py
|
| 18 |
|
| 19 | THIS_DIR=$(readlink -f $(dirname $0))
|
| 20 | readonly THIS_DIR
|
| 21 | REPO_ROOT=$(cd $THIS_DIR/.. && pwd)
|
| 22 | readonly REPO_ROOT
|
| 23 |
|
| 24 |
|
| 25 | readonly HTML_BASE_DIR=_release/VERSION
|
| 26 |
|
| 27 |
|
| 28 | log() {
|
| 29 | echo "$@" 1>&2
|
| 30 | }
|
| 31 |
|
| 32 | #
|
| 33 | # Deps (similar to doctools/cmark.sh and build/codegen.sh)
|
| 34 | #
|
| 35 |
|
| 36 | readonly MANDOC_DIR='_deps/mdocml-1.14.1'
|
| 37 |
|
| 38 | download-mandoc() {
|
| 39 | mkdir -p _deps
|
| 40 | wget --no-clobber --directory _deps \
|
| 41 | https://mandoc.bsd.lv/snapshots/mdocml-1.14.1.tar.gz
|
| 42 | }
|
| 43 |
|
| 44 | build-mandoc() {
|
| 45 | cd $MANDOC_DIR
|
| 46 | ./configure
|
| 47 | make
|
| 48 | }
|
| 49 |
|
| 50 | mandoc() {
|
| 51 | $MANDOC_DIR/mandoc "$@"
|
| 52 | }
|
| 53 |
|
| 54 | # Places version is used
|
| 55 | #
|
| 56 | # - in --version
|
| 57 | # - in URL for every page? inside the binary
|
| 58 | # - in titles for index, install, osh-quick-ref TOC, etc.
|
| 59 | # - in deployment script
|
| 60 |
|
| 61 | # Run with environment variable
|
| 62 | help-gen() {
|
| 63 | PYTHONPATH=.:vendor doctools/help_gen.py "$@"
|
| 64 | }
|
| 65 |
|
| 66 | cmark() {
|
| 67 | # h2 and h3 are shown in TOC. The blog uses "legacy" h3 and h4.
|
| 68 | PYTHONPATH=.:vendor doctools/cmark.py --toc-tag h2 --toc-tag h3 --toc-pretty-href "$@"
|
| 69 | }
|
| 70 |
|
| 71 | readonly MARKDOWN_DOCS=(
|
| 72 | published
|
| 73 |
|
| 74 | # polished
|
| 75 | getting-started
|
| 76 | portability
|
| 77 | known-differences
|
| 78 | ysh-error
|
| 79 | error-handling
|
| 80 | error-catalog
|
| 81 | json
|
| 82 | hay
|
| 83 | simple-word-eval
|
| 84 | quirks
|
| 85 | warts
|
| 86 |
|
| 87 | eggex
|
| 88 | ysh-regex-api
|
| 89 | upgrade-breakage
|
| 90 | ysh-tour
|
| 91 |
|
| 92 | style-guide
|
| 93 | novelties
|
| 94 |
|
| 95 | proc-func
|
| 96 | block-literals
|
| 97 | objects
|
| 98 | types
|
| 99 |
|
| 100 | pure-mode
|
| 101 |
|
| 102 | # Data language
|
| 103 | qsn
|
| 104 | qtt
|
| 105 | j8-notation
|
| 106 | htm8
|
| 107 | # Protocol
|
| 108 | pretty-printing
|
| 109 | stream-table-process
|
| 110 | byo
|
| 111 | ysh-doc-processing
|
| 112 |
|
| 113 | table-object-doc
|
| 114 |
|
| 115 | lib-osh
|
| 116 |
|
| 117 | doc-toolchain
|
| 118 | doc-plugins
|
| 119 | ul-table
|
| 120 | ul-table-compare
|
| 121 | idioms
|
| 122 | shell-idioms
|
| 123 | ysh-faq
|
| 124 |
|
| 125 | language-influences
|
| 126 | ysh-vs-python
|
| 127 | ysh-vs-shell
|
| 128 |
|
| 129 | syntactic-concepts
|
| 130 | syntax-feelings
|
| 131 | command-vs-expression-mode
|
| 132 |
|
| 133 | repo-overview
|
| 134 |
|
| 135 | # needs polish
|
| 136 | # Note: docs about the YSH are prefixed 'ysh-'.
|
| 137 | # data-model and command-vs-expression-mode span both OSH and YSH
|
| 138 |
|
| 139 | index
|
| 140 | faq-doc
|
| 141 |
|
| 142 | options
|
| 143 |
|
| 144 | old/index
|
| 145 | old/project-tour
|
| 146 | old/legacy-array
|
| 147 | old/ysh-keywords
|
| 148 | old/modules
|
| 149 | old/expression-language
|
| 150 | old/word-language
|
| 151 | old/errors
|
| 152 | old/ysh-builtins
|
| 153 |
|
| 154 | io-builtins
|
| 155 | unicode
|
| 156 | framing
|
| 157 | xtrace
|
| 158 | headless
|
| 159 | completion
|
| 160 | strings
|
| 161 | variables
|
| 162 |
|
| 163 | # Internal stuff
|
| 164 | interpreter-state
|
| 165 | process-model
|
| 166 | architecture-notes
|
| 167 | parser-architecture
|
| 168 | )
|
| 169 |
|
| 170 | # Bug fix: Plain $(date) can output unicode characters (e.g. in Japanese
|
| 171 | # locale), which is loaded by Python into say u'\u5e74'. But the default
|
| 172 | # encoding in Python 2 is still 'ascii', which means that '%s' % u_str may
|
| 173 | # fail.
|
| 174 | #
|
| 175 | # I believe --rfc-email should never output a Unicode character.
|
| 176 | #
|
| 177 | # A better fix would be to implement json_utf8.load(f), which doesn't decode
|
| 178 | # into unicode instances. This would remove useless conversions.
|
| 179 |
|
| 180 | default-doc-timestamp() {
|
| 181 | # Note: this flag doesn't exist on Alpine Linux
|
| 182 | if ! date --rfc-email; then
|
| 183 | echo '(error: No DOC_TIMESTAMP and no date --rfc-e-mail)'
|
| 184 | fi
|
| 185 | }
|
| 186 |
|
| 187 | DOC_TIMESTAMP=${DOC_TIMESTAMP:-$(default-doc-timestamp)}
|
| 188 |
|
| 189 | split-and-render() {
|
| 190 | local src=${1:-doc/known-differences.md}
|
| 191 |
|
| 192 | local rel_path=${src%'.md'} # doc/known-differences
|
| 193 | local tmp_prefix=_tmp/$rel_path # temp dir for splitting
|
| 194 |
|
| 195 | local out=${2:-$HTML_BASE_DIR/$rel_path.html}
|
| 196 | local web_url=${3:-'../web'}
|
| 197 | local quiet=${4:-}
|
| 198 |
|
| 199 | mkdir -v -p $(dirname $out) $tmp_prefix
|
| 200 |
|
| 201 | # Also add could add css_files. The one in the file takes precedence always?
|
| 202 |
|
| 203 | # css_files: a space-separated list
|
| 204 | # all_docs_url: so we link from doc/foo.html -> doc/
|
| 205 |
|
| 206 | local css_files="$web_url/base.css $web_url/manual.css $web_url/toc.css $web_url/language.css $web_url/code.css"
|
| 207 |
|
| 208 | PYTHONPATH='.:vendor' doctools/split_doc.py \
|
| 209 | -v build_timestamp="$DOC_TIMESTAMP" \
|
| 210 | -v oil_version="$OILS_VERSION" \
|
| 211 | -v css_files="$css_files" \
|
| 212 | -v all_docs_url='.' \
|
| 213 | -v repo_url="$src" \
|
| 214 | $src $tmp_prefix
|
| 215 |
|
| 216 | #ls -l _tmp/doc
|
| 217 | #head _tmp/doc/*
|
| 218 | #return
|
| 219 |
|
| 220 | # for ysh-tour code blocks
|
| 221 | local code_out=_tmp/code-blocks/$rel_path.txt
|
| 222 | mkdir -v -p $(dirname $code_out)
|
| 223 |
|
| 224 | cmark \
|
| 225 | --code-block-output $code_out \
|
| 226 | ${tmp_prefix}_meta.json ${tmp_prefix}_content.md > $out
|
| 227 |
|
| 228 | if test -z "$quiet"; then
|
| 229 | log "$tmp_prefix -> (doctools/cmark) -> $out"
|
| 230 | fi
|
| 231 | }
|
| 232 |
|
| 233 | render-from-kate() {
|
| 234 | ### Make it easier to configure Kate editor
|
| 235 |
|
| 236 | # It want to pass an absolute path
|
| 237 | # TODO: I can't figure out how to run this from Kate?
|
| 238 |
|
| 239 | local full_path=$1
|
| 240 |
|
| 241 | case $full_path in
|
| 242 | $REPO_ROOT/*)
|
| 243 | rel_path=${full_path#"$REPO_ROOT/"}
|
| 244 | echo "relative path = $rel_path"
|
| 245 | ;;
|
| 246 | *)
|
| 247 | die "$full_path should start with repo root $REPO_ROOT"
|
| 248 | ;;
|
| 249 | esac
|
| 250 |
|
| 251 | split-and-render $rel_path
|
| 252 | }
|
| 253 |
|
| 254 | # Special case for README
|
| 255 | # Do NOT split because we don't want front matter in the markdown source.
|
| 256 | render-only() {
|
| 257 | local src=${1:-README.md}
|
| 258 |
|
| 259 | local name
|
| 260 | case $src in
|
| 261 | *.md)
|
| 262 | name=$(basename $src .md)
|
| 263 | ;;
|
| 264 | *.txt)
|
| 265 | name=$(basename $src .txt)
|
| 266 | ;;
|
| 267 | *)
|
| 268 | name=$(basename $src)
|
| 269 | ;;
|
| 270 | esac
|
| 271 |
|
| 272 | local out=${2:-$HTML_BASE_DIR/doc/$name.html}
|
| 273 | local css_files=${3:-'../web/manual.css ../web/toc.css'}
|
| 274 | local title=${4:-'Oils Source Code'}
|
| 275 |
|
| 276 | local prefix=_tmp/doc/$name
|
| 277 |
|
| 278 | local meta=${prefix}_meta.json
|
| 279 | cat >$meta <<EOF
|
| 280 | { "title": "$title",
|
| 281 | "repo_url": "$src",
|
| 282 | "css_files": "$css_files",
|
| 283 | "all_docs_url": ".",
|
| 284 |
|
| 285 | "build_timestamp": "$DOC_TIMESTAMP",
|
| 286 | "oil_version": "$OILS_VERSION"
|
| 287 | }
|
| 288 | EOF
|
| 289 |
|
| 290 | cmark $meta $src > $out
|
| 291 | log "Wrote $out"
|
| 292 | }
|
| 293 |
|
| 294 | help-mirror-md() {
|
| 295 | echo '
|
| 296 | Oils Build `--help` Mirror
|
| 297 | =====
|
| 298 |
|
| 299 | <style>
|
| 300 | /* Similar to web/install.css */
|
| 301 | h1 { font-size: 1.5em; }
|
| 302 | h2 { font-size: 1.2em; }
|
| 303 |
|
| 304 | /* Exclude Markdown <pre><code> */
|
| 305 | code:not(pre code) {
|
| 306 | color: green;
|
| 307 | }
|
| 308 | </style>
|
| 309 |
|
| 310 | This doc mirrors the `--help` for the 3 shell tools in the build sytsem:
|
| 311 |
|
| 312 | 1. `configure` - Detect system features
|
| 313 | 1. `_build/oils.sh` - Compile `oils-for-unix` source into an executable
|
| 314 | 1. `install` - Install the executable, and symlinks to it
|
| 315 |
|
| 316 | <div id="toc">
|
| 317 | </div>
|
| 318 |
|
| 319 | ## Note: Usage is Different Than Autotools
|
| 320 |
|
| 321 | To minimize build deps, all 3 of these tools are hand-written POSIX shell
|
| 322 | scripts. So this build system does **not** use GNU autotools, and it does not
|
| 323 | use `make`.
|
| 324 |
|
| 325 | Keep these differences in mind:
|
| 326 |
|
| 327 | - Settings are configured with **either** flags or env vars, as described
|
| 328 | below.
|
| 329 | - For example, use `./configure --cxx-for-configure mycc`, not `CXX=mycc
|
| 330 | configure`.
|
| 331 | - If you pass `./configure --cxx-for-configure mycc`, you should also pass
|
| 332 | `_build/oils.sh --cxx mycc`. The flag value is not remembered.
|
| 333 |
|
| 334 | ## configure
|
| 335 |
|
| 336 | ```'
|
| 337 | ./configure --help
|
| 338 |
|
| 339 | echo '```
|
| 340 |
|
| 341 | ## _build/oils.sh
|
| 342 |
|
| 343 | ```'
|
| 344 |
|
| 345 | devtools/release-native.sh gen-shell-build
|
| 346 | _build/oils.sh --help
|
| 347 |
|
| 348 | echo '```
|
| 349 |
|
| 350 | ## install
|
| 351 |
|
| 352 | ```'
|
| 353 | ./install --help
|
| 354 | echo '```
|
| 355 |
|
| 356 | ## Links
|
| 357 |
|
| 358 | - [INSTALL.html](INSTALL.html) - Quick guide for end users.
|
| 359 | - [Oils Packaging Guidelines]($wiki) wiki
|
| 360 | - [Oils Packaging Tips]($wiki) wiki - free free to edit this page.
|
| 361 |
|
| 362 | '
|
| 363 | }
|
| 364 |
|
| 365 | help-mirror() {
|
| 366 | ### Mirror --help to HTML
|
| 367 |
|
| 368 | local md=_tmp/doc/help-mirror.md
|
| 369 |
|
| 370 | help-mirror-md > $md
|
| 371 |
|
| 372 | local web_dir='../web'
|
| 373 | #local css="$web_dir/base.css $web_dir/install.css $web_dir/toc.css"
|
| 374 | local css="$web_dir/base.css $web_dir/toc.css"
|
| 375 | render-only $md '' "$css" 'Oils Build Help Mirror'
|
| 376 | }
|
| 377 |
|
| 378 | special() {
|
| 379 | # TODO: do all READMEs
|
| 380 | split-and-render mycpp/README.md \
|
| 381 | $HTML_BASE_DIR/doc/oils-repo/mycpp/README.html \
|
| 382 | ../../../web
|
| 383 |
|
| 384 | # TODO: README can just be a pointer to other docs, like "Repo Overview"
|
| 385 | local web_dir='../../web'
|
| 386 | render-only 'README.md' $HTML_BASE_DIR/doc/oils-repo/README.html \
|
| 387 | "$web_dir/base.css $web_dir/manual.css $web_dir/toc.css" 'Oils Source Code'
|
| 388 |
|
| 389 | help-mirror
|
| 390 |
|
| 391 | local web_dir='../web'
|
| 392 | render-only INSTALL.txt '' \
|
| 393 | "$web_dir/base.css $web_dir/install.css" 'Installing Oils'
|
| 394 |
|
| 395 | render-only INSTALL-old.txt '' \
|
| 396 | "$web_dir/base.css $web_dir/install.css" 'Installing Oils - old CPython build'
|
| 397 |
|
| 398 | # These pages aren't in doc/
|
| 399 | split-and-render doc/release-index.md _tmp/release-index.html
|
| 400 | split-and-render doc/release-quality.md _tmp/release-quality.html
|
| 401 | }
|
| 402 |
|
| 403 | all-markdown() {
|
| 404 | make-dirs
|
| 405 |
|
| 406 | # TODO: We can set repo_url here! Then we don't need it for most docs.
|
| 407 | # split_doc.py can return {} if the doc doesn't start with ---
|
| 408 |
|
| 409 | #for d in doc/index.md doc/known-differences.md doc/*-manual.md \
|
| 410 | # doc/eggex.md doc/oil-options.md doc/oil-func-proc-block.md; do
|
| 411 | for d in "${MARKDOWN_DOCS[@]}"; do
|
| 412 | split-and-render doc/$d.md
|
| 413 | done
|
| 414 |
|
| 415 | special
|
| 416 | }
|
| 417 |
|
| 418 | redir-body() {
|
| 419 | local to_url=$1 # WARNING: no escaping
|
| 420 | cat <<EOF
|
| 421 | <head>
|
| 422 | <meta http-equiv="Refresh" content="0; URL=$to_url" />
|
| 423 | </head>
|
| 424 | EOF
|
| 425 | }
|
| 426 |
|
| 427 | redirect-pairs() {
|
| 428 | # we want want /release/latest/ URLs to still work
|
| 429 | cat <<EOF
|
| 430 | oil-language-tour ysh-tour
|
| 431 | oil-language-faq ysh-faq
|
| 432 | oil-help ysh-help
|
| 433 | oil-help-topics ysh-help-topics
|
| 434 | ysh-help ref/toc-ysh
|
| 435 | ysh-help-topics ref/toc-ysh
|
| 436 | EOF
|
| 437 | }
|
| 438 |
|
| 439 | all-redirects() {
|
| 440 | log '*** Writing redirects'
|
| 441 | redirect-pairs | while read -r from_page to_page; do
|
| 442 | redir-body "$to_page.html" | tee "_release/VERSION/doc/$from_page.html"
|
| 443 | done
|
| 444 | }
|
| 445 |
|
| 446 | # TODO: This could use some CSS.
|
| 447 | man-page() {
|
| 448 | local root_dir=${1:-_release/VERSION}
|
| 449 | mandoc -T html doc/osh.1 > $root_dir/osh.1.html
|
| 450 | ls -l $root_dir
|
| 451 | }
|
| 452 |
|
| 453 | # I want to ship the INSTALL file literally, so just mutate things
|
| 454 | _sed-ext() {
|
| 455 | sed --regexp-extended -i "$@"
|
| 456 | }
|
| 457 |
|
| 458 | update-src-versions() {
|
| 459 | # Update tarball names, etc.
|
| 460 | _sed-ext \
|
| 461 | "s/[0-9]+\.[0-9]+\.[a-z0-9]+/$OILS_VERSION/g" \
|
| 462 | doc/release-*.md INSTALL.txt INSTALL-old.txt README-native.txt
|
| 463 |
|
| 464 | # Update /release/0.8.4/ URL, etc.
|
| 465 | _sed-ext \
|
| 466 | "s;/release/[0-9]+\.[0-9]+\.[a-z0-9]+/;/release/$OILS_VERSION/;g" \
|
| 467 | doc/osh.1
|
| 468 | }
|
| 469 |
|
| 470 | #
|
| 471 | # Test Tools
|
| 472 | #
|
| 473 |
|
| 474 | split-doc-demo() {
|
| 475 | cat > _tmp/testdoc.md <<EOF
|
| 476 | ---
|
| 477 | title: foo
|
| 478 | ---
|
| 479 |
|
| 480 | Title
|
| 481 | =====
|
| 482 |
|
| 483 | hello
|
| 484 |
|
| 485 | EOF
|
| 486 |
|
| 487 | doctools/split_doc.py _tmp/testdoc.md _tmp/testdoc
|
| 488 |
|
| 489 | head _tmp/testdoc*
|
| 490 | }
|
| 491 |
|
| 492 | #
|
| 493 | # Help is both markdown and text
|
| 494 | #
|
| 495 |
|
| 496 | readonly TMP_DIR=_tmp/doc
|
| 497 | readonly CODE_BLOCK_DIR=_tmp/code-blocks
|
| 498 | readonly TEXT_DIR=_devbuild/help
|
| 499 | readonly HTML_DIR=_release/VERSION
|
| 500 | readonly CODE_DIR=_devbuild/gen
|
| 501 |
|
| 502 | cards-from-indices() {
|
| 503 | ### Make help cards
|
| 504 |
|
| 505 | for lang in osh ysh data; do
|
| 506 | help-gen cards-from-index $lang $TEXT_DIR \
|
| 507 | < $HTML_DIR/doc/ref/toc-$lang.html
|
| 508 | done
|
| 509 | }
|
| 510 |
|
| 511 | cards-from-chapters() {
|
| 512 | ### Turn h3 topics into cards
|
| 513 |
|
| 514 | local py_out=$CODE_DIR/help_meta.py
|
| 515 |
|
| 516 | mkdir -p _gen/frontend
|
| 517 | local cc_prefix=_gen/frontend/help_meta
|
| 518 |
|
| 519 | help-gen cards-from-chapters $TEXT_DIR $py_out $cc_prefix \
|
| 520 | $HTML_DIR/doc/ref/chap-*.html
|
| 521 | }
|
| 522 |
|
| 523 | ref-check() {
|
| 524 | help-gen ref-check \
|
| 525 | doc/ref/toc-*.md \
|
| 526 | _release/VERSION/doc/ref/chap-*.html
|
| 527 | }
|
| 528 |
|
| 529 | fmt-check() {
|
| 530 | PYTHONPATH=.:vendor doctools/fmt_check.py _release/VERSION/doc/ref/*.html
|
| 531 | }
|
| 532 |
|
| 533 |
|
| 534 | write-metrics() {
|
| 535 | ### Check indexes and chapters against each other
|
| 536 |
|
| 537 | local out=_release/VERSION/doc/metrics.txt
|
| 538 |
|
| 539 | log '*** ref-check'
|
| 540 |
|
| 541 | # send stderr to the log file too
|
| 542 | ref-check > $out 2>&1
|
| 543 |
|
| 544 | echo "Wrote $out"
|
| 545 | }
|
| 546 |
|
| 547 | tour() {
|
| 548 | ### Build the Tour of YSH, and execute code as validation
|
| 549 | local name=${1:-ysh-tour}
|
| 550 |
|
| 551 | split-and-render doc/$name.md
|
| 552 |
|
| 553 | local work_dir=$REPO_ROOT/_tmp/code-blocks/doc
|
| 554 |
|
| 555 | mkdir -p $work_dir/lib
|
| 556 |
|
| 557 | # Files used by module example
|
| 558 | touch $work_dir/{build,test}.sh
|
| 559 |
|
| 560 | cat >$work_dir/lines.txt <<'EOF'
|
| 561 | doc/hello.md
|
| 562 | "doc/with spaces.md"
|
| 563 | b'doc/with byte \yff.md'
|
| 564 | EOF
|
| 565 |
|
| 566 | cat >$work_dir/myargs.ysh <<EOF
|
| 567 | const __provide__ = :| proc1 p2 p3 |
|
| 568 |
|
| 569 | proc proc1 {
|
| 570 | echo proc1
|
| 571 | }
|
| 572 |
|
| 573 | proc p2 {
|
| 574 | echo p2
|
| 575 | }
|
| 576 |
|
| 577 | proc p3 {
|
| 578 | echo p3
|
| 579 | }
|
| 580 | EOF
|
| 581 |
|
| 582 | cat >$work_dir/demo.py <<EOF
|
| 583 | #!/usr/bin/env python
|
| 584 |
|
| 585 | print("hi")
|
| 586 | EOF
|
| 587 | chmod +x $work_dir/demo.py
|
| 588 |
|
| 589 | cat >$work_dir/lib/util.ysh <<EOF
|
| 590 | const __provide__ = :| log |
|
| 591 |
|
| 592 | proc log {
|
| 593 | echo @ARGV >&2
|
| 594 | }
|
| 595 | EOF
|
| 596 |
|
| 597 | pushd $work_dir
|
| 598 |
|
| 599 | # Prepend extra code
|
| 600 | cat >tour.ysh - $name.txt <<EOF
|
| 601 | func myMethod(self) {
|
| 602 | echo 'myMethod'
|
| 603 | }
|
| 604 |
|
| 605 | func mutatingMethod(self) {
|
| 606 | echo 'mutatingMethod'
|
| 607 | }
|
| 608 |
|
| 609 | func makeMyObject(x) {
|
| 610 | var methods = Object(null, {myMethod, 'M/mutatingMethod': mutatingMethod})
|
| 611 | return (Object(methods, {x}))
|
| 612 | }
|
| 613 | EOF
|
| 614 |
|
| 615 | # Fix: don't supply stdin!
|
| 616 | $REPO_ROOT/bin/ysh tour.ysh < /dev/null
|
| 617 | popd
|
| 618 |
|
| 619 | # My own dev tools
|
| 620 | # if test -d ~/vm-shared; then
|
| 621 | if false; then
|
| 622 | local path=_release/VERSION/doc/$name.html
|
| 623 | cp -v $path ~/vm-shared/$path
|
| 624 | fi
|
| 625 | }
|
| 626 |
|
| 627 | one() {
|
| 628 | ### Iterate on one doc quickly
|
| 629 |
|
| 630 | local name=${1:-options}
|
| 631 |
|
| 632 | split-and-render doc/$name.md
|
| 633 |
|
| 634 | # Make sure the doc has valid YSH code?
|
| 635 | # TODO: Maybe need an attribute for OSH or YSH
|
| 636 | pushd _tmp/code-blocks/doc
|
| 637 | $REPO_ROOT/bin/ysh $name.txt
|
| 638 | popd
|
| 639 |
|
| 640 | if test -d ~/vm-shared; then
|
| 641 | local out="${name%.md}.html"
|
| 642 | local path=_release/VERSION/$out
|
| 643 | cp -v $path ~/vm-shared/$path
|
| 644 | fi
|
| 645 | }
|
| 646 |
|
| 647 | make-dirs() {
|
| 648 | mkdir -p $TMP_DIR $CODE_BLOCK_DIR $TEXT_DIR $HTML_DIR/doc
|
| 649 | }
|
| 650 |
|
| 651 | one-ref() {
|
| 652 | local md=${1:-doc/ref/index.md}
|
| 653 | split-and-render $md '' '../../web'
|
| 654 | }
|
| 655 |
|
| 656 | indices-chapters() {
|
| 657 |
|
| 658 | log "Building doc/ref"
|
| 659 | local -a sources=( doc/ref/*.md )
|
| 660 | local -A pid_map=()
|
| 661 | for d in ${sources[@]}; do
|
| 662 | # do ~23 docs in parallel; this saves more than one second on my machine
|
| 663 | split-and-render $d '' '../../web' QUIET &
|
| 664 | pid_map[$!]=$d
|
| 665 | done
|
| 666 |
|
| 667 | local failed=''
|
| 668 | for pid in "${!pid_map[@]}"; do
|
| 669 | #echo "WAIT $pid"
|
| 670 |
|
| 671 | # Funny dance to get exit code
|
| 672 | set +o errexit
|
| 673 | wait $pid
|
| 674 | status=$?
|
| 675 | set -o errexit
|
| 676 |
|
| 677 | if test $status -ne 0; then
|
| 678 | local d=${pid_map[$pid]}
|
| 679 | echo
|
| 680 | echo "*** Building '$d' failed ***"
|
| 681 | echo
|
| 682 | failed=T
|
| 683 | fi
|
| 684 | done
|
| 685 |
|
| 686 | if test -n "$failed"; then
|
| 687 | return 1
|
| 688 | fi
|
| 689 | }
|
| 690 |
|
| 691 | all-ref() {
|
| 692 | ### Build doc/ref in text and HTML. Depends on libcmark.so
|
| 693 |
|
| 694 | rm -f $TEXT_DIR/*
|
| 695 | make-dirs
|
| 696 |
|
| 697 | indices-chapters
|
| 698 |
|
| 699 | # Note: if we want a $ref-topic shortcut, we might want to use Ninja to
|
| 700 | # extract topics from all chapters first, and then make help_meta.json, like
|
| 701 | # we have _devbuild/gen/help_meta.py.
|
| 702 |
|
| 703 | # Text cards
|
| 704 | cards-from-indices # 3 help_gen.py processes
|
| 705 | # A few text cards, and HELP_TOPICS dict for URLs, for flat namespace
|
| 706 | cards-from-chapters # 1 help_gen.py process
|
| 707 |
|
| 708 | return
|
| 709 |
|
| 710 | if command -v pysum; then
|
| 711 | # 19 KB of embedded help, seems OK. Biggest card is 'ysh-option'. Could
|
| 712 | # compress it.
|
| 713 | echo 'Size of embedded help:'
|
| 714 | ls -l $TEXT_DIR | tee /dev/stderr | awk '{print $5}' | pysum
|
| 715 | fi
|
| 716 | # Better sorting
|
| 717 | #LANG=C ls -l $TEXT_DIR
|
| 718 | }
|
| 719 |
|
| 720 | _copy-path() {
|
| 721 | local src=$1 dest=$2
|
| 722 | mkdir -p $(dirname $dest)
|
| 723 | cp -v $src $dest
|
| 724 | }
|
| 725 |
|
| 726 | copy-web() {
|
| 727 | find web \
|
| 728 | \( -name _tmp -a -prune \) -o \
|
| 729 | \( -name '*.css' -o -name '*.js' \) -a -printf '%p _release/VERSION/%p\n' |
|
| 730 | xargs -n 2 -- $0 _copy-path
|
| 731 | }
|
| 732 |
|
| 733 | pretty-size() {
|
| 734 | local path=$1
|
| 735 | stat --format '%s' "$path" | python -c '
|
| 736 | import sys
|
| 737 | num_bytes = int(sys.stdin.read())
|
| 738 | print "{:,}".format(num_bytes)
|
| 739 | '
|
| 740 | }
|
| 741 |
|
| 742 | # NOTE: It might be better to link to files like this in the /release/ tree.
|
| 743 | # Although I am not signing them.
|
| 744 |
|
| 745 | # https://nodejs.org/dist/v8.11.4/SHASUMS256.txt.asc
|
| 746 |
|
| 747 | tarball-links-row-html() {
|
| 748 | local version=$1
|
| 749 |
|
| 750 | cat <<EOF
|
| 751 | <tr class="file-table-heading">
|
| 752 | <td></td>
|
| 753 | <td>File / SHA256 checksum</td>
|
| 754 | <td class="size">Size</td>
|
| 755 | <td></td>
|
| 756 | </tr>
|
| 757 | EOF
|
| 758 |
|
| 759 | # We switched to .gz for oils-for-unix
|
| 760 | # Note: legacy names are needed for old releases
|
| 761 | for name in \
|
| 762 | oils-for-unix-$version.tar.{gz,xz} \
|
| 763 | oils-ref-$version.tar.gz \
|
| 764 | oil-$version.tar.{gz,xz} \
|
| 765 | oil-native-$version.tar.xz; do
|
| 766 |
|
| 767 | local url="/download/$name" # The server URL
|
| 768 | local path="../oils.pub__deploy/download/$name"
|
| 769 |
|
| 770 | # Don't show tarballs that don't exist
|
| 771 | if ! test -f "$path"; then
|
| 772 | case $name in
|
| 773 | oils-for-unix-*|oil-native-*)
|
| 774 | ;;
|
| 775 | *)
|
| 776 | log "Warning: Expected tarball $name to exist"
|
| 777 | ;;
|
| 778 | esac
|
| 779 | continue
|
| 780 | fi
|
| 781 |
|
| 782 | local checksum
|
| 783 | checksum=$(sha256sum $path | awk '{print $1}')
|
| 784 | local size
|
| 785 | size=$(pretty-size $path)
|
| 786 |
|
| 787 | # TODO: Port this to oil with "commas" extension.
|
| 788 |
|
| 789 | # Three columns: date, version, and links
|
| 790 | cat <<EOF
|
| 791 | <tr>
|
| 792 | <td></td>
|
| 793 | <td class="filename"><a href="$url">$name</a></td>
|
| 794 | <td class="size">$size</td>
|
| 795 | </tr>
|
| 796 | <tr>
|
| 797 | <td></td>
|
| 798 | <td colspan=2 class="checksum">$checksum</td>
|
| 799 | </tr>
|
| 800 | EOF
|
| 801 | done
|
| 802 | }
|
| 803 |
|
| 804 | this-release-links() {
|
| 805 | echo '<div class="file-table">'
|
| 806 | echo '<table>'
|
| 807 | tarball-links-row-html "$OILS_VERSION"
|
| 808 | echo '</table>'
|
| 809 | echo '</div>'
|
| 810 | }
|
| 811 |
|
| 812 | # Turn HTML comment into a download link
|
| 813 | add-date-and-links() {
|
| 814 | local snippet
|
| 815 | snippet=$(this-release-links)
|
| 816 |
|
| 817 | awk -v date=$1 -v snippet="$snippet" '
|
| 818 | /<!-- REPLACE_WITH_DOWNLOAD_LINKS -->/ {
|
| 819 | print(snippet)
|
| 820 | next
|
| 821 | }
|
| 822 |
|
| 823 | /<!-- REPLACE_WITH_DATE -->/ {
|
| 824 | print(date)
|
| 825 | next
|
| 826 | }
|
| 827 |
|
| 828 | # Everything else
|
| 829 | { print }
|
| 830 | '
|
| 831 | }
|
| 832 |
|
| 833 | patch-release-pages() {
|
| 834 | local release_date
|
| 835 | release_date=$(cat _build/release-date.txt)
|
| 836 |
|
| 837 | local root=_release/VERSION
|
| 838 |
|
| 839 | add-date-and-links $release_date < _tmp/release-index.html > $root/index.html
|
| 840 | add-date-and-links $release_date < _tmp/release-quality.html > $root/quality.html
|
| 841 | }
|
| 842 |
|
| 843 | copy-release-pages() {
|
| 844 | ### For testing without releasing
|
| 845 |
|
| 846 | cat < _tmp/release-index.html > $root/index.html
|
| 847 | cat < _tmp/release-quality.html > $root/quality.html
|
| 848 | }
|
| 849 |
|
| 850 | run-for-release() {
|
| 851 | ### Build a tree. Requires _build/release-date.txt to exist
|
| 852 |
|
| 853 | local root=_release/VERSION
|
| 854 | mkdir -p $root/{doc,test,pub}
|
| 855 |
|
| 856 | tour
|
| 857 |
|
| 858 | # Metadata
|
| 859 | cp -v _build/release-date.txt oils-version.txt $root
|
| 860 |
|
| 861 | # Docs
|
| 862 | # Writes _release/VERSION and _tmp/release-index.html
|
| 863 | all-markdown
|
| 864 | all-ref
|
| 865 | all-redirects # backward compat
|
| 866 |
|
| 867 | fmt-check # Needs to run *after* we build the HTML
|
| 868 |
|
| 869 | patch-release-pages
|
| 870 |
|
| 871 | write-metrics
|
| 872 |
|
| 873 | # Problem: You can't preview it without .wwz!
|
| 874 | # Maybe have local redirects VERSION/test/wild/ to
|
| 875 | #
|
| 876 | # Instead of linking, I should compress them all here.
|
| 877 |
|
| 878 | copy-web
|
| 879 |
|
| 880 | if command -v tree >/dev/null; then
|
| 881 | tree $root
|
| 882 | else
|
| 883 | find $root
|
| 884 | fi
|
| 885 | }
|
| 886 |
|
| 887 | soil-run() {
|
| 888 | build/stamp.sh write-release-date
|
| 889 |
|
| 890 | run-for-release
|
| 891 | }
|
| 892 |
|
| 893 | #
|
| 894 | # Generator
|
| 895 | #
|
| 896 |
|
| 897 | _gen-readme-index() {
|
| 898 | # Use relative markdown links
|
| 899 | echo '
|
| 900 | Oils Repo READMEs
|
| 901 | =================
|
| 902 |
|
| 903 | This page is useful for finding docs that are out of date.
|
| 904 |
|
| 905 | Generate it with:
|
| 906 |
|
| 907 | build/doc.sh gen-readme-index
|
| 908 |
|
| 909 | '
|
| 910 | for path in */README.md; do
|
| 911 | echo "- [$path]($path)"
|
| 912 | done
|
| 913 | }
|
| 914 |
|
| 915 | gen-readme-index() {
|
| 916 | _gen-readme-index > README-index.md
|
| 917 | }
|
| 918 |
|
| 919 | #
|
| 920 | # Golden tests
|
| 921 | #
|
| 922 | # $0 golden-tree
|
| 923 | # $0 determinstic-build # with new code
|
| 924 | # $0 compare-golden
|
| 925 |
|
| 926 | deterministic() {
|
| 927 | # build without varying timestamp
|
| 928 | DOC_TIMESTAMP='GOLD' $0 soil-run
|
| 929 | }
|
| 930 |
|
| 931 | golden-tree() {
|
| 932 | rm -r -f _release/VERSION/ _release/VERSION_gold/
|
| 933 | deterministic
|
| 934 | cp -r _release/VERSION/ _release/VERSION_gold
|
| 935 | }
|
| 936 |
|
| 937 | compare-golden() {
|
| 938 | diff -r -u _release/VERSION_gold _release/VERSION/
|
| 939 | }
|
| 940 |
|
| 941 | "$@"
|
| 942 |
|