kind-portal

This library adapts the Portal visualization tool to support the Kindly convention for Clojure literate programming.

For example, this adapter allows people to view a single visualization created inside a notebook that would otherwise be rendered with Clay. Kindly establishes a common ground for Clojure learning resources that would work across different tools. Portal provides an interactive way to view data inside your IDE or in a separate window.

Usage

Add org.scicloj/kind-portal and djblue/portal as dev dependencies.

If you prefer, you can add them as a user dev dependencies instead, so that they are available in all projects. See $HOME/.clojure/deps.edn as described in deps_sources.

Interaction

From the REPL you can require kind-portal, and then send forms to be visualized:

(scicloj.kind-portal.v1.api/kindly-submit-context {:form '(+ 1 2)})

However, visualizations are most useful when you can invoke them with a key-binding.

It is recommended to create a REPL command to invoke kindly-submit-context:

(do (require '[scicloj.kind-portal.v1.api :as kp])
    (kp/kindly-submit-context {:form (quote ~form-before-caret)}))

Emacs CIDER

Emacs users can make use of the kind-portal.el package.

Preparing values

Another use of kind-portal is functional, through the prepare function, which prepares a Kindly context as a Portal-ready values.

This may be used by other tools (e.g., Clay) that may wish to display Portal viewers.

For example:

(require '[scicloj.kind-portal.v1.api :as kind-portal]
         '[scicloj.kindly.v4.kind :as kind])

(def portal-ready-value
  (kind-portal/prepare
   {:value (kind/hiccup [:div [:p "hello"]])}))

portal-ready-value
#_=> [:div [:p "hello"]]

(meta portal-ready-value)
#_=> {:kindly/kind :kind/hiccup,
      :portal.viewer/default :portal.viewer/hiccup}

Examples

Various kinds

See the examples namespace to try it out.

Portal looks like this:

Standalone HTML

The standalone-html namespace demonstrates how one may generate a standalone HTML file containing Portal views annotated by Kindly and prepared using kind-portal. See the resulting HTML page here.

This is a self-contained demonstration of the method internally used by Clay to embed Portal views in notebooks.

To generate the page, call the generate! function.