emmy.sci, publish library as Clerk notebooks

.clj-kondo/config.edn

@@ -10,7 +10,8 @@
  :linters
  {:unsorted-required-namespaces {:level :warning}
   :redundant-fn-wrapper {:level :warning}
-  :single-key-in {:level :warning}}
+  :single-key-in {:level :warning}
+  :unresolved-namespace {:exclude [nextjournal.clerk]}}
 
  :lint-as
  {clojure.test.check.clojure-test/defspec clojure.test/deftest

.dir-locals.el

@@ -3,4 +3,7 @@
      (cider-default-cljs-repl . node)))
  (clojurec-mode
   . ((cider-preferred-build-tool . clojure-cli)
-     (cider-clojure-cli-aliases . ":test:cljs:dev/repl"))))
+     (cider-clojure-cli-aliases . ":test:cljs:nextjournal/clerk:dev")))
+ (clojure-mode
+  . ((cider-preferred-build-tool . clojure-cli)
+     (cider-clojure-cli-aliases . ":test:cljs:nextjournal/clerk:dev"))))

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [unreleased]
 
+## [0.30.0]
+
+- #124:
+
+  - Upgrades `babashka/sci` to 0.7.39.
+
+  - Adds a working `bb repl` command to the repository.
+
+  - Renames `emmy.env.sci` => `emmy.sci`, and adds an `emmy.sci/install!`
+    command to make it easier to install all namespaces into a shared SCI
+    context.
+
+  - Renames `context-opts` in the new `emmy.sci` to `emmy.sci/config`, to match
+    the `sci-configs` style.
+
+  The full library is now published to `https://emmy.mentat.org` as a series of
+  Clerk notebooks. This required a dependency on https://clerk-utils.mentat.org,
+  but no actual Clerk dependency in the library.
+
 - #119:
 
   - Removes support for `:flat` compilation mode (this was a step toward
@@ -818,7 +837,7 @@
     - The folds in this namespace now follow the fold contract laid out in
       `sicmutils.algebra.fold`, implementing all three arities correctly.
 
-    - I realized that the fold implementation here should /not/ return a full
+    - I realized that the fold implementation here should _not_ return a full
       row every time it processes a previous row; a far better `present`
       implementation would return the best estimate so far. Then you could build
       a `scan` from that fold to see the estimates evolve lazily as new points

README.md

@@ -6,7 +6,7 @@
 > docs links, please visit the corresponding page at
 > https://github.com/sicmutils/sicmutils.
 
-A Clojure(script) implementation of the [scmutils][scmutils-refman-url] system
+A Clojure(Script) implementation of the [scmutils][scmutils-refman-url] system
 for math and physics investigations in the Clojure and ClojureScript languages.
 Emmy provides facilities for
 
@@ -54,23 +54,40 @@ Geometry][fdg-book-url] by G.J. Sussman and J. Wisdom.
 > with rich support for [TeX](https://en.wikipedia.org/wiki/TeX) rendering and
 > plotting.
 
-Install Emmy into your Clojure(Script) project using the instructions at its
+Install `Emmy` into your Clojure(Script) project using the instructions at its
 Clojars page:
 
-[![Clojars Project](https://img.shields.io/clojars/v/org.mentat/emmy.svg)](https://clojars.org/org.mentat/emmy)
+[![Clojars Project][clojars]][clojars-url]
 
-Initialize the `emmy.env` "Batteries Included" environment at the REPL:
+Or grab the most recent code using a Git dependency:
 
-```clojure
-(require '[emmy.env :as env])
-(env/bootstrap-repl!)
+```clj
+;; deps
+{io.github.mentat-collective/emmy
+  {:git/sha "$GIT_SHA"}}
 ```
 
-Visit the [Emmy Tutorial on
-Nextjournal](https://nextjournal.com/try/samritchie/sicmutils) to try all of the
-examples below in your browser with no setup required:
+Require `emmy.env` in your Clojure(Script) namespace:
+
+```clj
+(ns my-app
+  (:require [emmy.env :as e :refer :all]))
+```
 
-<img width="1152" alt="nje" src="https://user-images.githubusercontent.com/462255/109587851-9e1be280-7abc-11eb-9369-6d56519fb3cd.png">
+Or clone this repository:
+
+```sh
+git clone git@github.com:mentat-collective/emmy.git
+cd emmy
+```
+
+then install [the Clojure command line
+tool](https://clojure.org/guides/install_clojure) and run the following command
+to launch a REPL with `emmy.env` already loaded:
+
+```sh
+clj -M:test:dev:repl
+```
 
 Math works as expected (see
 [Generics](https://cljdoc.org/d/org.mentat/emmy/CURRENT/doc/basics/generics) for

bb.edn

@@ -1,21 +1,69 @@
-{:deps
- {io.github.clj-kondo/clj-kondo-bb
-  {:git/tag "v2023.01.20" :git/sha "adfc7df"}}
-
+{:deps {org.babashka/http-server {:mvn/version "0.1.11"}
+        org.babashka/cli {:mvn/version "0.2.23"}
+        io.github.clj-kondo/clj-kondo-bb
+        {:git/tag "v2023.01.20" :git/sha "adfc7df"}}
  :tasks
- {test:clj
+ {:requires ([babashka.cli :as cli])
+  :init
+  (do (def cli-opts
+        (cli/parse-opts *command-line-args* {:coerce {:port :int}}))
+
+      (defn X [cmd]
+        (let [args *command-line-args*]
+          (if (even? (count args))
+            (apply shell cmd args)
+            (do (println "Please supply an even number of arguments!")
+                (System/exit 1))))))
+
+  repl
+  {:doc "Start a REPL with `emmy.env` loaded."
+   :task (shell "clj -M:test:dev:repl")}
+
+  test:clj
   {:doc "Run CLJ tests."
    :task (shell "clojure -X:test:runner")}
 
   test:cljs
   {:doc "Run CLJS tests."
    :task (shell "npm run test")}
 
+  clerk-watch
+  {:doc "Runs `user/serve!` with a watcher process generating custom JS."
+   :task (X "clojure -X:nextjournal/clerk user/serve!")}
+
+  build-static
+  {:doc "Generate a fresh static build."
+   :task
+   (apply shell
+          "clojure -X:nextjournal/clerk"
+          *command-line-args*)}
+
+  serve
+  {:doc "Serve static assets"
+   :requires ([babashka.http-server :as server])
+   :task (server/exec
+          (merge {:port 8080
+                  :dir "public/build"}
+                 cli-opts))}
+
+  release-gh-pages
+  {:doc "Generate a fresh static build and release it to Github Pages."
+   :task
+   (do (shell "rm -rf public/build")
+       (run 'build-static)
+       (shell "npm run gh-pages"))}
+
+  publish-local
+  {:doc "Generate a fresh static build and start a local webserver."
+   :task
+   (do (run 'build-static)
+       (run 'serve))}
+
   release
   {:doc "Release the library to Clojars."
    :task (shell "clojure -T:build publish")}
 
   lint
   {:doc "Lint with clj-kondo."
    :task (exec 'clj-kondo.core/exec)
-   :exec-args {:lint ["src" "test"]}}}}
+   :exec-args {:lint ["src" "test" "dev"]}}}}

deps.edn

@@ -8,26 +8,28 @@
   com.taoensso/timbre {:mvn/version "6.0.4"}
   dm3/stopwatch {:mvn/version "0.1.1" :exclusions [org.clojure/clojurescript]}
   org.apache.commons/commons-math3 {:mvn/version "3.6.1"}
-  org.babashka/sci {:mvn/version "0.6.37"}}
+  org.babashka/sci {:mvn/version "0.7.39"}
+  org.mentat/clerk-utils {:mvn/version "0.5.0"}}
 
  :aliases
- {:dev {:extra-paths ["dev"]
-        :jvm-opts ["-Xms6g" "-Xmx8g" "-server"]}
+ {:dev
+  {:extra-paths ["dev"]
+   :extra-deps
+   {io.github.nextjournal/clerk {:git/sha "4329fa31b75bf26c04bdcc803a52fe642baec56e"}}
+   :jvm-opts ["-Xms6g" "-Xmx8g" "-server"]}
 
   ;; This entry sets up the REPL environment for local development. Run a full
-  ;; repl with `clj -A:test:dev:repl`.
+  ;; repl with `clj -M:test:dev:repl`.
   :repl
   {:main-opts
    ["-e"
-    "(do (require 'emmy.env)
-         (in-ns 'emmy.env)
-         (str \"Clojure \" (clojure-version)))"
+    "(do (require 'emmy.env) (in-ns 'emmy.env) (println \"Clojure\" (clojure-version)))"
     "-r"]}
 
   :cljs
   {:extra-deps
-   {org.clojure/clojurescript {:mvn/version "1.11.60"}
-    thheller/shadow-cljs {:mvn/version "2.20.14"}}}
+   {thheller/shadow-cljs {:mvn/version "2.20.14"}
+    org.clojure/clojurescript {:mvn/version "1.11.60"}}}
 
   :test
   ;; layer this in to get access to everything in the test directory, plus the
@@ -36,36 +38,40 @@
    :extra-deps
    {com.gfredericks/test.chuck {:mvn/version "0.2.14"}
     io.github.cognitect-labs/test-runner
-    {:git/tag "v0.5.0"
-     :git/sha "b3fd0d2"}
-    io.github.nextjournal/clerk
-    {:git/sha "d08c26043efe19a92fe33dd9eb4499e304e4cff7"}
+    {:git/tag "v0.5.0" :git/sha "b3fd0d2"}
     org.clojure/test.check {:mvn/version "1.1.1"}
-    hiccup/hiccup {:mvn/version "1.0.5"}
+    io.github.nextjournal/clerk {:git/sha "4329fa31b75bf26c04bdcc803a52fe642baec56e"}
     same/ish {:mvn/version "0.1.4"}}}
 
-  :build
-  ;; build.clj tool.
-  {:deps {io.github.clojure/tools.build {:git/tag "v0.8.2" :git/sha "ba1a2bf"}
-          slipset/deps-deploy {:mvn/version "0.2.0"}}
-   :ns-default build}
-
   ;; See https://github.com/cognitect-labs/test-runner for invocation
-  ;; instructions.
+  ;; instructions, or call `clojure -X:test:runner`.
   :runner
   {:main-opts ["-m" "cognitect.test-runner"]
    :exec-fn cognitect.test-runner.api/test
    :exec-args ["test"]}
 
+  :nextjournal/clerk
+  {:extra-paths ["dev"]
+   :extra-deps
+   {org.clojure/clojure       {:mvn/version "1.11.1"}
+    org.clojure/clojurescript {:mvn/version "1.11.60"}
+    io.github.nextjournal/clerk
+    {:git/sha "4329fa31b75bf26c04bdcc803a52fe642baec56e"}
+    io.github.nextjournal/clerk.render
+    {:git/url "https://github.com/nextjournal/clerk"
+     :git/sha "4329fa31b75bf26c04bdcc803a52fe642baec56e"
+     :deps/root "render"}}
+   :exec-fn user/build!}
+
   :coverage
   ;; Invoke with clj -M:test:coverage <args>
   {:main-opts ["-m" "cloverage.coverage"
                "-p" "src"
                "-s" "test"]
    :extra-deps {cloverage/cloverage {:mvn/version "1.2.4"}}}
 
-  :lint
-  ;; Invoke with clj -M:test:lint <kondo-args>
-  {:extra-paths ["test"]
-   :main-opts ["-m" "clj-kondo.main"]
-   :replace-deps {clj-kondo/clj-kondo {:mvn/version "RELEASE"}}}}}
+  :build
+  ;; build.clj tool.
+  {:deps {io.github.clojure/tools.build {:git/tag "v0.8.2" :git/sha "ba1a2bf"}
+          slipset/deps-deploy {:mvn/version "0.2.0"}}
+   :ns-default build}}}

dev/emmy/sci_extensions.cljs

@@ -0,0 +1,6 @@
+(ns emmy.sci-extensions
+  "SCI environment extensions, meant to apply to Emmy's Clerk documentation
+  build."
+  (:require [emmy.sci]))
+
+(emmy.sci/install!)

dev/user.clj

@@ -1,15 +1,47 @@
 (ns user
-  (:require [nextjournal.clerk :as clerk]
-            [emmy.env]))
+  (:require [mentat.clerk-utils.build :as b]
+            [nextjournal.clerk.config :as cc]))
 
-(alter-var-root #'*warn-on-reflection* (constantly true))
+(try (requiring-resolve 'cljs.analyzer.api/ns-resolve)
+     (catch Exception _ nil))
+(require '[emmy.env])
 
-(comment
-  ;; Activate this line to start the clerk server.
-  (clerk/serve!
-   {:browse? true :port 7778}))
+;; This is required to prevent Clerk from realizing long
+;; computationally-intensive sequences on render / static build.
+(alter-var-root #'cc/*bounded-count-limit*
+                (constantly 10))
 
 (comment
-  ;; call clerk/show on files to be rendered:
-  (clerk/show! "src/emmy/calculus/derivative.cljc")
-  (clerk/show! "src/emmy/differential.cljc"))
+  (alter-var-root #'*warn-on-reflection* (constantly true)))
+
+(def index
+  "TODO: Create a meaningful index here."
+  "dev/index.md")
+
+(def notebooks
+  ["src/emmy/**/**.cljc"
+   "src/emmy/**/**.clj"])
+
+(def defaults
+  {#_#_:index index
+   :browse? true
+   :watch-paths ["src" "dev"]})
+
+(def static-defaults
+  (assoc defaults
+         :browse? false
+         :paths notebooks
+         :cname "emmy.mentat.org"
+         :git/url "https://github.com/mentat-collective/emmy"))
+
+(defn serve!
+  ([] (serve! {}))
+  ([opts]
+   (b/serve!
+    (merge defaults opts))))
+
+(def halt! b/halt!)
+
+(defn build! [opts]
+  (b/build!
+   (merge static-defaults opts)))