forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
feat: update deploy script and workspace for site content
Switch dune-workspace from --shell docsite to --shell jon-shell so the
jon-site package renders with the correct shell layout. Update
deploy-site.sh to document the jon-site integration, add the
odoc-jon-shell prerequisite, and list site content key pages.
The site content (blog, notebooks, reference) is picked up
automatically by `dune build @doc` via the jon-site documentation
stanza. No interactive cells exist in site content yet, so the
universe deployment path remains unchanged.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+40
-4
+27
-3
deploy-site.sh
+27
-3
deploy-site.sh
···
1
1
#!/bin/bash
2
-
# Deploy the full odoc documentation site.
2
+
# Deploy the full odoc documentation site including jon.recoil.org content.
3
3
#
4
4
# Builds all packages' docs, extension support files, x-ocaml runtime,
5
5
# and a jtw universe for the interactive demos.
6
6
#
7
+
# The jon-site package (in site/) is included automatically by
8
+
# `dune build @doc` since it has a (documentation ...) stanza.
9
+
#
10
+
# Shell configuration:
11
+
# dune-workspace sets html_flags globally for all packages.
12
+
# Currently using --shell jon-shell for the site content layout.
13
+
# Per-package shell selection is not possible in a single build;
14
+
# production may need a two-pass build:
15
+
# Pass 1: --shell docsite -> build reference docs
16
+
# Pass 2: --shell jon-shell -> rebuild site content
17
+
# See dune-workspace comments for details.
18
+
#
7
19
# Prerequisites:
8
20
# - opam switch "default" with the custom dune fork (3.21, html_flags support)
9
21
# - js_top_worker packages installed in the default switch
10
22
# (opam pin + opam install js_top_worker js_top_worker-web)
23
+
# - odoc-jon-shell installed (opam install odoc-jon-shell)
11
24
#
12
25
# Usage:
13
26
# ./deploy-site.sh # build everything and serve on port 8080
···
28
41
eval "$(opam env)"
29
42
30
43
echo "=== Step 1: Build and install into opam switch ==="
31
-
echo " (needed so odoc finds extensions + x-ocaml.js via dune-site)"
44
+
echo " (needed so odoc finds extensions + x-ocaml.js + jon-shell via dune-site)"
32
45
cd "$MONO"
33
46
dune build @install
34
47
dune install 2>&1 | tail -3
35
48
36
49
echo ""
37
50
echo "=== Step 2: Generate documentation ==="
51
+
echo " (builds all packages including jon-site content)"
38
52
echo " (odoc copies extension support files including x-ocaml.js automatically)"
39
53
dune build @doc 2>&1 | tail -5 || true
40
54
···
45
59
46
60
echo ""
47
61
echo "=== Step 4: Deploy universe ==="
62
+
# The universe needs to be accessible from pages that use interactive OCaml.
63
+
# Currently that's only the odoc-interactive-extension demo pages.
64
+
# When site content gains interactive cells (ocamltop/deferred-js blocks),
65
+
# the universe will also need to be accessible from jon-site pages.
48
66
rm -rf "$DOC_HTML/odoc-interactive-extension/universe"
49
67
cp -r "$MONO/_build/default/odoc-interactive-extension/doc/universe" \
50
68
"$DOC_HTML/odoc-interactive-extension/universe"
···
55
73
echo ""
56
74
echo "Site at: $DOC_HTML/"
57
75
echo ""
58
-
echo "Key pages:"
76
+
echo "Key pages — reference docs:"
59
77
echo " /index.html — package index"
60
78
echo " /odoc-admonition-extension/index.html — admonition demos"
61
79
echo " /odoc-dot-extension/index.html — graphviz demos"
···
64
82
echo " /odoc-rfc-extension/index.html — RFC demos"
65
83
echo " /odoc-scrollycode-extension/index.html — scrollycode demos"
66
84
echo " /odoc-interactive-extension/demo1.html — interactive OCaml"
85
+
echo ""
86
+
echo "Key pages — site content (jon-site):"
87
+
echo " /jon-site/index.html — site home"
88
+
echo " /jon-site/blog/index.html — blog index"
89
+
echo " /jon-site/notebooks/index.html — notebooks index"
90
+
echo " /jon-site/notebooks/foundations/index.html — foundations of CS"
67
91
68
92
if $SERVE; then
69
93
echo ""
+13
-1
dune-workspace
+13
-1
dune-workspace
···
1
1
(lang dune 3.21)
2
2
3
+
; Shell configuration for odoc HTML generation.
4
+
;
5
+
; html_flags are applied globally to all packages in `dune build @doc`.
6
+
; Per-package shell selection is not currently possible within a single
7
+
; build invocation. For production, a two-pass build (first with
8
+
; --shell docsite for reference docs, then --shell jon-shell for site
9
+
; content) or upstream per-package html_flags support would be needed.
10
+
;
11
+
; For this development branch, we use --shell jon-shell globally so
12
+
; site content renders correctly. Reference docs will use the jon-shell
13
+
; layout too, which is acceptable for development.
14
+
3
15
(env
4
16
(dev
5
17
(odoc
6
-
(html_flags --shell docsite)
18
+
(html_flags --shell jon-shell)
7
19
)))