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

1015 lines, 500 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 _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
696 # TODO: add more docs here
697}
698
699one() {
700 ### Iterate on one doc quickly
701
702 local name=${1:-options}
703
704 split-and-render doc/$name.md
705
706 # Make sure the doc has valid YSH code?
707 # TODO: Maybe need an attribute for OSH or YSH
708 pushd _tmp/code-blocks/doc
709 $REPO_ROOT/bin/ysh $name.txt
710 popd
711
712 if test -d ~/vm-shared; then
713 local out="${name%.md}.html"
714 local path=_release/VERSION/$out
715 cp -v $path ~/vm-shared/$path
716 fi
717}
718
719make-dirs() {
720 mkdir -p $TMP_DIR $CODE_BLOCK_DIR $TEXT_DIR $HTML_DIR/doc
721}
722
723one-ref() {
724 local md=${1:-doc/ref/index.md}
725 split-and-render $md '' '../../web'
726}
727
728indices-chapters() {
729
730 log "Building doc/ref"
731 local -a sources=( doc/ref/*.md )
732 local -A pid_map=()
733 for d in ${sources[@]}; do
734 # do ~23 docs in parallel; this saves more than one second on my machine
735 split-and-render $d '' '../../web' QUIET &
736 pid_map[$!]=$d
737 done
738
739 local failed=''
740 for pid in "${!pid_map[@]}"; do
741 #echo "WAIT $pid"
742
743 # Funny dance to get exit code
744 set +o errexit
745 wait $pid
746 status=$?
747 set -o errexit
748
749 if test $status -ne 0; then
750 local d=${pid_map[$pid]}
751 echo
752 echo "*** Building '$d' failed ***"
753 echo
754 failed=T
755 fi
756 done
757
758 if test -n "$failed"; then
759 return 1
760 fi
761}
762
763all-ref() {
764 ### Build doc/ref in text and HTML. Depends on libcmark.so
765
766 rm -f $TEXT_DIR/*
767 make-dirs
768
769 indices-chapters
770
771 # Note: if we want a $ref-topic shortcut, we might want to use Ninja to
772 # extract topics from all chapters first, and then make help_meta.json, like
773 # we have _devbuild/gen/help_meta.py.
774
775 # Text cards
776 cards-from-indices # 3 help_gen.py processes
777 # A few text cards, and HELP_TOPICS dict for URLs, for flat namespace
778 cards-from-chapters # 1 help_gen.py process
779
780 return
781
782 if command -v pysum; then
783 # 19 KB of embedded help, seems OK. Biggest card is 'ysh-option'. Could
784 # compress it.
785 echo 'Size of embedded help:'
786 ls -l $TEXT_DIR | tee /dev/stderr | awk '{print $5}' | pysum
787 fi
788 # Better sorting
789 #LANG=C ls -l $TEXT_DIR
790}
791
792_copy-path() {
793 local src=$1 dest=$2
794 mkdir -p $(dirname $dest)
795 cp -v $src $dest
796}
797
798copy-web() {
799 find web \
800 \( -name _tmp -a -prune \) -o \
801 \( -name '*.css' -o -name '*.js' \) -a -printf '%p _release/VERSION/%p\n' |
802 xargs -n 2 -- $0 _copy-path
803}
804
805pretty-size() {
806 local path=$1
807 stat --format '%s' "$path" | python -c '
808import sys
809num_bytes = int(sys.stdin.read())
810print "{:,}".format(num_bytes)
811'
812}
813
814# NOTE: It might be better to link to files like this in the /release/ tree.
815# Although I am not signing them.
816
817# https://nodejs.org/dist/v8.11.4/SHASUMS256.txt.asc
818
819tarball-links-row-html() {
820 local version=$1
821
822 cat <<EOF
823<tr class="file-table-heading">
824 <td></td>
825 <td>File / SHA256 checksum</td>
826 <td class="size">Size</td>
827 <td></td>
828</tr>
829EOF
830
831 # We switched to .gz for oils-for-unix
832 # Note: legacy names are needed for old releases
833 for name in \
834 oils-for-unix-$version.tar.{gz,xz} \
835 oils-ref-$version.tar.gz \
836 oil-$version.tar.{gz,xz} \
837 oil-native-$version.tar.xz; do
838
839 local url="/download/$name" # The server URL
840 local path="../oils.pub__deploy/download/$name"
841
842 # Don't show tarballs that don't exist
843 if ! test -f "$path"; then
844 case $name in
845 oils-for-unix-*|oil-native-*)
846 ;;
847 *)
848 log "Warning: Expected tarball $name to exist"
849 ;;
850 esac
851 continue
852 fi
853
854 local checksum
855 checksum=$(sha256sum $path | awk '{print $1}')
856 local size
857 size=$(pretty-size $path)
858
859 # TODO: Port this to oil with "commas" extension.
860
861 # Three columns: date, version, and links
862 cat <<EOF
863 <tr>
864 <td></td>
865 <td class="filename"><a href="$url">$name</a></td>
866 <td class="size">$size</td>
867 </tr>
868 <tr>
869 <td></td>
870 <td colspan=2 class="checksum">$checksum</td>
871 </tr>
872EOF
873 done
874}
875
876this-release-links() {
877 echo '<div class="file-table">'
878 echo '<table>'
879 tarball-links-row-html "$OILS_VERSION"
880 echo '</table>'
881 echo '</div>'
882}
883
884# Turn HTML comment into a download link
885add-date-and-links() {
886 local snippet
887 snippet=$(this-release-links)
888
889 awk -v date=$1 -v snippet="$snippet" '
890 /<!-- REPLACE_WITH_DOWNLOAD_LINKS -->/ {
891 print(snippet)
892 next
893 }
894
895 /<!-- REPLACE_WITH_DATE -->/ {
896 print(date)
897 next
898 }
899
900 # Everything else
901 { print }
902 '
903}
904
905patch-release-pages() {
906 local release_date
907 release_date=$(cat _build/release-date.txt)
908
909 local root=_release/VERSION
910
911 add-date-and-links $release_date < _tmp/release-index.html > $root/index.html
912 add-date-and-links $release_date < _tmp/release-quality.html > $root/quality.html
913}
914
915copy-release-pages() {
916 ### For testing without releasing
917
918 cat < _tmp/release-index.html > $root/index.html
919 cat < _tmp/release-quality.html > $root/quality.html
920}
921
922run-for-release() {
923 ### Build a tree. Requires _build/release-date.txt to exist
924
925 local root=_release/VERSION
926 mkdir -p $root/{doc,test,pub}
927
928 ysh-tour
929 run-code-all
930
931 # Metadata
932 cp -v _build/release-date.txt oils-version.txt $root
933
934 # Docs
935 # Writes _release/VERSION and _tmp/release-index.html
936 all-markdown
937 all-ref
938 all-redirects # backward compat
939
940 fmt-check # Needs to run *after* we build the HTML
941
942 patch-release-pages
943
944 write-metrics
945
946 # Problem: You can't preview it without .wwz!
947 # Maybe have local redirects VERSION/test/wild/ to
948 #
949 # Instead of linking, I should compress them all here.
950
951 copy-web
952
953 if command -v tree >/dev/null; then
954 tree $root
955 else
956 find $root
957 fi
958}
959
960soil-run() {
961 build/stamp.sh write-release-date
962
963 run-for-release
964}
965
966#
967# Generator
968#
969
970_gen-readme-index() {
971 # Use relative markdown links
972 echo '
973Oils Repo READMEs
974=================
975
976This page is useful for finding docs that are out of date.
977
978Generate it with:
979
980 build/doc.sh gen-readme-index
981
982'
983 for path in */README.md; do
984 echo "- [$path]($path)"
985 done
986}
987
988gen-readme-index() {
989 _gen-readme-index > README-index.md
990}
991
992#
993# Golden tests
994#
995# $0 golden-tree
996# $0 determinstic-build # with new code
997# $0 compare-golden
998
999deterministic() {
1000 # build without varying timestamp
1001 DOC_TIMESTAMP='GOLD' $0 soil-run
1002}
1003
1004golden-tree() {
1005 rm -r -f _release/VERSION/ _release/VERSION_gold/
1006 deterministic
1007 cp -r _release/VERSION/ _release/VERSION_gold
1008}
1009
1010compare-golden() {
1011 diff -r -u _release/VERSION_gold _release/VERSION/
1012}
1013
1014task-five "$@"
1015