OILS / build / doc.sh View on Github | oils.pub

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