SCI live docs

.github/workflows/docs-workflow.yml

@@ -69,6 +69,56 @@ jobs:
           name: klipse-cljs-cache
           path: docs/klipse/klipse-cljs-cache.tar.xz
 
+  # This job builds the re-frame :docs app and uploads it as an artifact.
+  # The app renders code blocks for the reader reader to edit & evaluate.
+
+  re-frame-docs-app:
+    name: Re-frame Docs App
+    runs-on: ubuntu-20.04
+    container:
+      image: ghcr.io/day8/dockerfile-for-dev-ci-image/dev-ci:1
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - name: Checkout Current Branch
+        uses: actions/checkout@v2
+      - name: Maven cache
+        id: maven-cache
+        uses: actions/cache@v1
+        with:
+          path: /root/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('project.clj', '.github/workflows/**') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
+      - name: Run lein docs
+        if: steps.maven-cache.outputs.cache-hit != 'true'
+        env:
+          CLOJARS_USERNAME: ${{ secrets.CLOJARS_USERNAME }}
+          CLOJARS_TOKEN: ${{ secrets.CLOJARS_TOKEN }}
+          GITHUB_USERNAME: ${{ github.actor }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          lein docs
+      - name: Run lein -o docs
+        if: steps.maven-cache.outputs.cache-hit == 'true'
+        env:
+          CLOJARS_USERNAME: ${{ secrets.CLOJARS_USERNAME }}
+          CLOJARS_TOKEN: ${{ secrets.CLOJARS_TOKEN }}
+          GITHUB_USERNAME: ${{ github.actor }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          lein -o docs
+      - name: Create re-frame-docs App Artifact
+        working-directory: docs
+        run: |
+          tar Jcf re-frame-docs-app.tar.xz js
+      - name: Upload re-frame-docs App Artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: re-frame-docs-app
+          path: docs/re-frame-docs-app.tar.xz
+
   # MkDocs is the actual static site generator. It downloads the api-re-frame.core.md and Klipse cache artifacts then generates
   # additional files based on configuration and markdown.
   mkdocs:
@@ -87,13 +137,14 @@ jobs:
         with:
           name: api-re-frame.core.md
           path: docs
-      - name: Download Klipse CLJS Cache Artifact
-        uses: actions/download-artifact@v1
+      - name: Download re-frame-docs App Artifact
+        uses: actions/download-artifact@v2
         with:
-          name: klipse-cljs-cache
-      - name: Extract Klipse CLJS Cache Artifact
-        working-directory: docs/klipse
-        run: tar Jxf ../../klipse-cljs-cache/klipse-cljs-cache.tar.xz
+          name: re-frame-docs-app
+          path: docs
+      - name: Extract re-frame-docs App Artifact
+        working-directory: docs
+        run: tar Jxf re-frame-docs-app.tar.xz
       - name: Build MkDocs Documentation
         run: mkdocs build
       - name: Create MkDocs Artifact

.gitignore

@@ -17,6 +17,7 @@ compiled/
 misc/
 /examples/todomvc/resources/public/js/
 /examples/simple/resources/public/js/
+/docs/js
 .floo
 .flooignore
 node_modules/

docs/README.md

@@ -15,7 +15,7 @@ The re-frame website is largly built using a static site generator:
 a [Material UI](https://material.io/) theme for the `mkdocs` static site generator.
 
 The live re-frame website is built [via Github actions](https://github.com/day8/re-frame/blob/feature/mkdocs/.github/workflows/docs-workflow.yml)
-which stitch together the docs, the API and the klipse artifacts.
+which stitch together the docs, the API and the docs app.
 
 ## To Build Locally
 
@@ -63,7 +63,6 @@ We've made various modifications to the base template supplied by the theme ...
 
 Notably adds
 - Google Font stylesheets
-- klipse custom stylesheets and javascripts
 - our own stylesheets for overriding some styles
 
 `overrides/partials/footer.html`
@@ -81,18 +80,4 @@ Removes trailing dash in page title due to empty site name.
 Our own custom styles.
 
 `stylesheets/codehilite-monokai.css`
-Our own port of the monokai theme to codehilite.
-
-`stylesheets/codemirror.css`
-Copy of https://github.com/viebel/klipse/blob/57e5312e88425811183a838f63afd4a92077fada/dist/codemirror.css
-with FiraCode removed.
-
-Incls syntax highlighting 'theme' around lines ~100-130.
-
-`javascripts/klipse_plugin.js`
-Copy of https://github.com/viebel/klipse/blob/57e5312e88425811183a838f63afd4a92077fada/dist/klipse_plugin.js
-
-## Using Klipse
-
-On some pages we use klipse for live coding. 
-See [`docs/klipse/README.md`](klipse/README.md).
+Our own port of the monokai theme to codehilite.

docs/clojurescript.md

@@ -1,7 +1,3 @@
----
-klipse: true
----
-
 > This document is currently in alpha test.
 >
 > If you review it, could you please let me know:
@@ -135,16 +131,33 @@ You are going to be surprised and delighted with the simplicity of "evaluation".
 | `#!clj {1 1 2 2}`   | `#!clj {1 1 2 2}`           |  Yep, same  |
 
 
-Below, you can start evaluating live on this page. Enter an expression into the following editor 
-and it will be evaluated. The result of the evaluation will be shown in the box below the editor.
-
-XXX inline REPL will go here. In the meantime, use [this external one](https://jaredforsyth.com/reepl/)
-
+Below, you can start evaluating live on this page. 
+Click the **Eval** button, or change the expression, and it will be evaluated. 
+The result of the evaluation will be shown in the box below the editor.
 
 Try these experiments:
 
-   - {:a 1 :a 4} -- oops 
-   - forget to close a parens ??
+<div class="cm-doc" data-cm-doc-no-eval-on-init>
+{:a 1 :a 4}
+<div class="cm-doc-validator">
+(fn duplicate-keys [{:keys [return-str]}]
+  (when (re-find #"duplicate key" return-str)
+    [:span "Oops! A map can only have 1 of a given key. Try changing "
+     [:code ":a 4"]
+     " to "
+     [:code ":b 4"] "."]))
+</div>
+</div>
+
+<div class="cm-doc" data-cm-doc-no-eval-on-init>
+[:apple :orange :banana
+ <div class="cm-doc-validator">
+ (fn eof-vector [{:keys [return-str]}]
+   (when (re-find #"EOF" return-str)
+     [:span "Forgot to close the form? Try adding " [:code "]"] " to the end."]))
+ </div>
+</div>
+
    - XXX other basic examples?
 
 So, let's now talk about the two exceptions `lists` and `symbols` ...
@@ -175,14 +188,33 @@ Example symbol evaluations:
     Wait. Isn't `#!clj +` an operator?  No. Clojure doesn't have operators. 
     Instead, `#!clj +` is a symbol, and it is bound to a function - one which adds. Anyway, more soon.
 
-
-XXX inline REPL will go here. In the meantime use [this external one](https://jaredforsyth.com/reepl/)
-
 Try these experiments:
 
-   - `#!clj inc`
-   - `#!clj [inc dec +]`       <--- and array of symbols
-   - `#!clj {inc 5}`           <--- strange but possible
+<div class="cm-doc" data-cm-doc-no-eval-on-init>>
+ inc
+ <div class="cm-doc-validator">
+ (fn function-object [{:keys [status]}]
+   (when (#{:success} status)
+     [:span "Functions are technically objects, and cljs represents them by printing "
+      [:code "object[qualified$name]"]]))
+ </div>
+</div>
+ <div class="cm-doc" data-cm-doc-no-eval-on-init>
+ [inc dec +]
+  <div class="cm-doc-validator">
+ (fn function-vec-item [{:keys [status]}]
+   (when (#{:success} status)
+     "This is simply three items in a vector. Just because they're functions does not mean you're calling them."))
+ </div>
+</div>
+<div class="cm-doc" data-cm-doc-no-eval-on-init>
+{inc 5}
+ <div class="cm-doc-validator">
+ (fn function-vec-item [{:keys [status]}]
+   (when (#{:success} status)
+     "Nearly anything can be a map key."))
+ </div>
+</div>
 
 ## Evaluating Lists
 
@@ -239,9 +271,14 @@ Let's start evaluating, live. Type into the following editor. Click Ctrl-click t
   - try `(odd? 5)` 
   - try `(count [1 2 3])`
 
-XXX inline REPL will go here. In the meantime use [this external one](https://jaredforsyth.com/reepl/)
-
-
+<div class="cm-doc" data-cm-doc-no-eval-on-init>
+ <div class="cm-doc-validator">
+ (fn arithmetic-arity [{:keys [status source-form]}]
+   (when (and (#{:success} status)
+              (#{'(+ 1) '(+) '(*)} source-form))
+     "Consider this either very intuitive, or very unintuitive."))
+ </div>
+</div>
 
 ---
 
@@ -276,12 +313,9 @@ More:
 
 Evaluate these experiments yourself (any surprises?):
 
-  - `#!clj (inc (dec 1))`
-  - `#!clj (odd? (inc (dec 1)))`
-  - `#!clj (= (inc (dec 1)) 1)`
-
-XXX inline REPL will go here. In the meantime use [this external one](https://jaredforsyth.com/reepl/)
-
+  - <div class="cm-doc" data-cm-doc-no-eval-on-init>(inc (dec 1))</div>
+  - <div class="cm-doc" data-cm-doc-no-eval-on-init>(odd? (inc (dec 1)))</div>
+  - <div class="cm-doc" data-cm-doc-no-eval-on-init>(= (inc (dec 1)) 1)</div>
 
 ---
 ## Keywords
@@ -327,11 +361,9 @@ To give you a taste of where this can go, here they are used as the keys in a ha
 
 Evaluate these experiments yourself (any surprises?):
 
-  - `#!clj (namespace :a)` 
-  - `#!clj (keyword (name :a))`
-  - `#!clj (keyword (namespace :a/b) (name :a/b))`
-
-XXX inline REPL will go here. In the meantime use [this external one](https://jaredforsyth.com/reepl/)
+<div class="cm-doc" data-cm-doc-no-eval-on-init>(namespace :a)</div> 
+<div class="cm-doc" data-cm-doc-no-eval-on-init>(keyword (name :a))</div>
+<div class="cm-doc" data-cm-doc-no-eval-on-init>(keyword (namespace :a/b) (name :a/b))</div>
 
 ---
 
@@ -414,11 +446,11 @@ is evaluated depending on the result of that `test`. One element remains unevalu
 
 Possible experiments: 
 
-  - check if `(if true)` is valid. 
-  - explore what is "truthy", via  `(if "hello" true false)` or `(if [] true false)` or `(if nil true false)`
+  - check if `#!clj (if true)` is valid. 
+  - explore what is "truthy", via  `#!clj (if "hello" true false)` or `#!clj (if [] true false)` or `#!clj (if nil true false)`
 
+<div class="cm-doc" data-cm-doc-no-eval-on-init></div>
 
-XXX inline REPL will go here. In the meantime use [this external one](https://jaredforsyth.com/reepl/)
 
 ---
 ## `#!clj fn`
@@ -488,28 +520,21 @@ The body of the function, `#!clj (+ num 1)`, will be evaluated with the `#!clj n
 
 Try these experiments:
 
-```cljs
-((fn [x] [x x]) 4)
-```
-or
-```cljs
-((fn [x y] {x y}) :a 4)
-```
-or
-```clj
-((fn []))
-```
-or
 
-```cljs
-((fn [yes?] {:a (if yes? "yes")}) true)
-```
+<div class="cm-doc" data-cm-doc-no-eval-on-init>((fn [x] [x x]) 4)</div>
+
+<div class="cm-doc" data-cm-doc-no-eval-on-init>((fn [x y] {x y}) :a 4)</div>
+
+<div class="cm-doc" data-cm-doc-no-eval-on-init>((fn []))</div>
+
+<div class="cm-doc" data-cm-doc-no-eval-on-init>((fn [yes?] {:a (if yes? "yes")}) true)</div>
+
 what if, instead, we called this function with `#!clj false`.
 
 You won't see this written in normal ClojureScript code, because it is weird, but here's a puzzle:
-```clj
-(((fn  [] inc)) 4)
-```
+
+<div class="cm-doc" data-cm-doc-no-eval-on-init>(((fn  [] inc)) 4)</div>
+
 What is the evaluation? Note: there is an extra set of parens around the `#!clj fn` form.
 
 
@@ -667,25 +692,21 @@ evaluates to `#!clj "the pen"`. Phew!
 evaluates to `#!clj {:winner-is "the pen"}`
 
 `#!clj let` is often used within a `#!clj defn`: 
-```clj 
+<div class="cm-doc">
 (defn greet
   [name friendly?]
   (let [greeting (if friendly? "Hello " "Go away ")]
-    [:div greeting name])
-```
+    [:div greeting name]))
+</div>
 
 XXX experiment with greet 
 
-```clj
-(greet "Mum" true)
-```
+<div class="cm-doc" cm-doc-no-eval-on-init>(greet "Mum" true)</div>
 
-```clj
-(greet "Noisy Neighbours" false)
-```
+<div class="cm-doc" data-cm-doc-no-eval-on-init>(greet "Noisy Neighbours" false)</div>
 
 In this particular, we could have got away with no using a `let`, like this: 
-```clj 
+``` clj
 (defn greet
   [name friendly?]
   [:div (if friendly? "Hello " "Go away ") name)