Liking cljdoc? Tell your friends :D

reval GitHub Actions status |pink-gorilla/revalCodecov ProjectClojars Project

reval

  • reval stands for reproduceable [namespace=notebook] evaluation
  • an eval result can be just the normal value, or it can be converted to hiccup
  • our hiccup format has a little extra: it can include custom types. Of course custom types need special browser rendering code, but we ship that too.

DEMO - Get Started

  • clone this repo
  • Run clj -X:goldly-docs. Open Browser on Port 8000
  • Open the repo in your preferred ide. Connect to nrepl on port 8000.
  • demo/demo/scratchpad.clj or Eval demo/demo/notebook.clj

scratchpad

  • you can send vizualisations of your clj expressions to the scratchpad
  • ->scratchpad sends the vizualisation to the browser.

Use it in your project

  • add a dependency to pinkgorilla/goldly-docs.
  • create a goldly config similar to demo/goldly-reval.edn
  • Add this alias to your deps.edn
 :goldly-docs
  {:extra-paths ["demo" "test"] ; to show static files (not auto generated ones)
   :extra-deps {org.pinkgorilla/goldly-docs {:mvn/version "RELEASE"}}
   :exec-fn goldly-server.app/goldly-server-run!
   :exec-args {:profile "jetty"
               :config "demo/goldly-reval.edn"}}

Now you can use your custom project in the same way as before, but get vizualisations.

configuration

The devtools config we use (in goldly-docs)

:devtools {:rdocument  {:storage-root "demo/rdocument/"
                         :url-root "/api/rdocument/file/"}
            :collections {:user [:clj "user/notebook/"]
                          :demo [:clj "demo/notebook/"]}}
(reval.config/set-config!
 {:storage-root "demo/rdocument/"
  :url-root "/api/rdocument/file/"})

By default storage root is "/tmp/rdocument/".

reproduceable storage

Example

Lets evaluate two namespaces:

  (eval-notebook "demo.notebook.apple)
  (eval-notebook "demo.notebook.banana)

Now say demo.notebook.banana includes a BufferedImage, then upon then the reproduceable document folder will look like this

   rdocument/demo/notebook/apple/notebook.edn
   rdocument/demo/notebook/banana/notebook.edn
   rdocument/demo/notebook/banana/67770344-1424-4803-a9aa-01e21cb4ce39.png

why use a notebook ?

  • clj cannot be evaled in the browser
  • eval takes time
  • eval might need extra dependencies or data
  • recalculate periodically a report that can be easily vizualised.
  • documentation
  • examples

For Developers

clj -M:test

If some of the types cannot be found do rm .cpcache -r. Multimethods and protocols sometimes are a little tricky.

Can you improve this documentation?Edit on GitHub

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close