Prep for 0.1.0 release (#21)

.github/workflows/gh-pages.yml

@@ -32,7 +32,7 @@ jobs:
           version: '0.8.156'
 
       - name: Build static site
-        run: bb github-pages
+        run: bb publish-gh-pages
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [unreleased]
+
+## 0.1.0
+
+First real release!
+
+- Added full complement of components
+- Published fleshed-out documentation notebook at https://jsxgraph.mentat.org

DEVELOPING.md

@@ -1,37 +1,72 @@
+## Note about Fork
+
+This library is currently using my fork of jsxgraph at
+https://github.com/sritchie/jsxgraph and published to
+https://www.npmjs.com/package/@mentatcollective/jsxgraph, but these changes
+should appear upstream soon and we can back off to the official library.
+
 ## Dev Dependencies
 
 `clj`, `shadow-cljs`, `node` and `babashka`.
 
-## Releasing Github Pages
+## Github Pages, Docs Notebook
+
+The project's [Github Pages site](https://jsxgraph.mentat.org) hosts an
+interactive [Clerk](https://github.com/nextjournal/clerk) notebook demonstrating
+the library's use.
 
-TODO discuss the documentation notebook, how we build it, how we use Clerk etc.'
+### Local Notebook Dev
 
-To generate the Github Pages site in the `public` folder, run:
+To start a shadow-cljs process watcher for the JS required to run the Clerk
+notebook, run
 
 ```
-bb github-pages
+bb dev-notebook
 ```
 
-This is run by the Github Action to actually publish.
+Then start a Clojure process however you like, and run `(user/start!)` to run
+the Clerk server. This command should open up `localhost:7777`.
 
-To locally generate a copy of the documentation notebook, run
+### Github Pages Static Build
+
+To test the Pages build locally:
 
 ```
 bb publish-local
 ```
 
-After the build is complete, visit http://127.0.0.1:8080/ to see the production
-build of the documentation notebook.
+This will generate the static site in `public`, start a development http server
+and open up a browser window (http://127.0.0.1:8080/) with the production build
+of the documentation notebook.
+
+### Pages Build
+
+To build and release to Github Pages:
+
+```
+bb release-gh-pages
+```
+
+This will ship the site to https://jsxgraph.mentat.org.
 
 ## Publishing to Clojars
 
-- Update the version in build.clj
-- Make a new Github Release
+The template for the project's `pom.xml` lives at
+[`template/pom.xml`](https://github.com/mentat-collective/jsxgraph.cljs/blob/main/template/pom.xml).
+
+To create a new release:
+
+- Update the version in
+  [build.clj](https://github.com/mentat-collective/jsxgraph.cljs/blob/main/build.clj)
+- Make a new [Github
+  Release](https://github.com/mentat-collective/jsxgraph.cljs/releases) with tag
+  `v<the-new-version>`.
 
-Launching the release will create a new tag and trigger the following command:
+Submitting the release will create the new tag and trigger the following
+command:
 
 ```
-clojure -T:build publish
+bb release
 ```
 
 The new release will appear on Clojars.

README.md

@@ -1,25 +1,98 @@
-# jsxgraph.cljs
-
-A light ClojureScript wrapper over [JSXGraph][JSXGRAPH].
+# JSXGraph.cljs
 
 [![Build Status](https://github.com/mentat-collective/jsxgraph.cljs/actions/workflows/kondo.yml/badge.svg?branch=main)](https://github.com/mentat-collective/jsxgraph.cljs/actions/workflows/kondo.yml)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/mentat-collective/jsxgraph.cljs/blob/main/LICENSE)
 [![cljdoc badge](https://cljdoc.org/badge/org.mentat/jsxgraph.cljs)](https://cljdoc.org/d/org.mentat/jsxgraph.cljs/CURRENT)
 [![Clojars Project](https://img.shields.io/clojars/v/org.mentat/jsxgraph.cljs.svg)](https://clojars.org/org.mentat/jsxgraph.cljs)
 
-In progress!
+[JSXGraph][JSXGraph] is a JavaScript library that lets you build 2-dimensional
+scenes full of geometric objects, function curves and interactive UI elements,
+potentially with many complex constraints defined between these objects.
+
+[JSXGraph.cljs](https://github.com/mentat-collective/jsxgraph.cljs) extends
+JSXGraph with a [React][REACT] / [Reagent][REAGENT] component that makes it easy to define
+JSXGraph constructions inside of a user interface built with Clojurescript.
+
+## Quickstart
+
+Install `jsxgraph.cljs` into your Clojurescript project using the instructions
+at its Clojars page:
+
+[![Clojars Project](https://img.shields.io/clojars/v/org.mentat/jsxgraph.cljs.svg)](https://clojars.org/org.mentat/jsxgraph.cljs)
+
+Require `jsxgraph.core` in your namespace:
+
+```clj
+(ns my-app
+   (:require [jsxgraph.core :as jsx]))
+```
+
+Create your first `jsx/JSXGraph` board, populated with two points and an arrow
+between them:
+
+```clj
+(cljs
+ [jsx/JSXGraph {:boundingbox [-3 3 3 -3] :axis true}
+  [jsx/Point {:name "A" :size 1 :parents [-1 1]}]
+  [jsx/Point {:id "B" :name "BEE!" :size 1 :parents [2 -1]}]
+  [jsx/Arrow {:size 4
+              :parents ["A" "B"]}]])
+```
+
+![2022-12-08 14 25 32](https://user-images.githubusercontent.com/69635/206570839-2fb1c4a9-dbb0-4c39-ac63-be5fc1ac4900.gif)
+
+Here's a more complex example of an interactive vector field, implemented
+[here](https://jsxgraph.mentat.org/#Vector%20Field):
 
-- how to use / require the library
-- usage example
-- notebook link and source
-- how to convert from jsxgraph proper...
+![2022-12-08 10 31 18](https://user-images.githubusercontent.com/69635/206570865-7b24e561-2c21-4b79-a665-41644c5e6f65.gif)
 
-## JSXGraph Examples
+See the project's [interactive documentation
+notebook](https://jsxgraph.mentat.org) for more guides and examples.
 
-- TODO get the examples directory linked
+## Interactive Documentation via Clerk
+
+The project's [interactive documentation](https://jsxgraph.mentat.org) was
+generated using Nextjournal's [Clerk](https://github.com/nextjournal/clerk). If
+you'd like to edit or play with the documentation, you'll need to install
+
+- [node.js](https://nodejs.org/en/)
+- The [clojure command line tool](https://clojure.org/guides/install_clojure)
+- [Babashka](https://github.com/babashka/babashka#installation)
+
+Once this is done, run this command in one terminal window to build and serve the custom JS required by the notebook:
+
+```
+bb dev-notebook
+```
+
+In another terminal window, run
+
+```
+bb start-clerk
+```
+
+This should open a browser window to `http://localhost:7777` with the contents
+of the documentation notebook. Any edits you make to `dev/jsxgraph/notebook.clj`
+will be picked up and displayed in the browser on save.
+
+## Thanks and Support
+
+To support this work and my other open source projects, consider sponsoring me
+via my [GitHub Sponsors page](https://github.com/sponsors/sritchie). Thank you
+to my current sponsors!
+
+I'm grateful to [Clojurists Together](https://www.clojuriststogether.org/) for
+financial support during this library's creation. Please consider [becoming a
+member](https://www.clojuriststogether.org/developers/) to support this work and
+projects like it.
 
 ## License
 
-[MIT](LICENSE).
+Copyright © 2022 Sam Ritchie.
+
+Distributed under the [MIT License](LICENSE). See [LICENSE](LICENSE).
 
-[JSXGRAPH]: https://jsxgraph.org
+[CLJS]: https://clojurescript.org/
+[JSXGRAPH]: https://jsxgraph.org/
+[REACT]: https://reactjs.org/
+[REAGENT]: https://reagent-project.github.io/

bb.edn

@@ -2,7 +2,7 @@
  {sha
   (let [sha (-> (shell {:out :string} "git rev-parse HEAD")
                 (:out)
-                (clojure.string/trim ))
+                (clojure.string/trim))
         file "public/index.html"]
     (-> (slurp file)
         (clojure.string/replace "$GIT_SHA" sha)
@@ -12,17 +12,22 @@
   (do (shell "npm install")
       (shell "npm run watch-clerk"))
 
-  github-pages
-  (do (shell "npm install")
-      (shell "npm run release-clerk")
-      (shell "clojure -X:nextjournal/clerk user/github-pages!")
-      (run 'sha))
+  start-clerk
+  (shell "clojure -X:dev:nextjournal/clerk user/start!")
 
-  publish-local
-  (do (shell "npm install")
+  publish-gh-pages
+  (do (shell "npm ci")
       (shell "npm run release-clerk")
-      (shell "clojure -X:nextjournal/clerk user/publish-local!")
+      (shell "clojure -X:dev:nextjournal/clerk user/github-pages!")
       (run 'sha)
+      (spit "./public/CNAME" "jsxgraph.mentat.org"))
+
+  release-gh-pages
+  (do (run 'publish-gh-pages)
+      (shell "npm run gh-pages"))
+
+  publish-local
+  (do (run 'publish-gh-pages)
       (shell "npm run serve"))
 
   release

build.clj

@@ -5,7 +5,7 @@
 ;; ## Variables
 
 (def lib 'org.mentat/jsxgraph.cljs)
-(def version "0.0.1")
+(def version "0.1.0")
 
 (defn- ->version
   ([] version)

deps.edn

@@ -10,15 +10,14 @@
   :nextjournal/clerk
   {:extra-paths ["dev"]
    :extra-deps
-   {io.github.nextjournal/clerk.viewer
-    {:git/url "https://github.com/nextjournal/clerk.git"
-     :git/sha "f18afd7e6165748765ea43c23604cc1965f20e35"
-     :deps/root "viewer"}}
-   :exec-fn nextjournal.clerk/build!
-   :exec-args {:index "dev/jsxgraph/notebook.clj"
-               :bundle? false
-               :out-path "public/build"
-               :extra-namespaces [jsxgraph.clerk-ui]}}
+   {io.github.nextjournal/clerk {:mvn/version "0.11.603"}
+
+    applied-science/js-interop {:mvn/version "0.3.3"}
+    org.babashka/sci {:mvn/version "0.4.33"}
+    reagent/reagent {:mvn/version "1.1.1"}
+    io.github.babashka/sci.configs {:git/sha "fcd367c6a6115c5c4e41f3a08ee5a8d5b3387a18"}
+    io.github.nextjournal/viewers {:git/sha "3284aae7379bde3fcf41d17c663bed421fb31d6d"}
+    metosin/reitit-frontend {:mvn/version "0.5.15"}}}
 
   :build
   {:deps {io.github.clojure/tools.build {:git/tag "v0.8.2" :git/sha "ba1a2bf"}

dev/jsxgraph/clerk_ui.cljc

@@ -1,7 +1,7 @@
 (ns jsxgraph.clerk-ui
   (:require #?(:cljs [jsxgraph.core])
-            #?(:clj [nextjournal.clerk :as clerk])
-            #?(:cljs [nextjournal.clerk.sci-env :refer [!sci-ctx]])
+            #?(:clj  [nextjournal.clerk :as clerk])
+            #?(:cljs [nextjournal.clerk.sci-viewer :as sv])
             #?(:cljs [sci.core :as sci]))
   #?(:cljs
      (:require-macros [jsxgraph.clerk-ui])))
@@ -12,7 +12,7 @@
 ;; library's CLJS code in the Clerk notebooks that document the library.
 
 #?(:cljs
-   (swap! !sci-ctx
+   (swap! sv/!sci-ctx
           sci/merge-opts
           {:classes    {'Math js/Math}
            :aliases    {'jsx 'jsxgraph.core}