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