notespace.v2.tutorial-test

Intro

This is a notespace – a namespace that is a sequence of notes. It is intented to be a tutorial about creating and using notespaces.

It is recommended to read this notespace alongside its rendered result.

Computing and rendering

To use notespace, require the namespace notespace.v2.note, bringing the symbols of the relevant note kinds to your own namespace using :refer. For example, if you want to use notes of kind :md, you may like to (require '[notespace.v2.note :refer [note-md]]). More about note kinds – below.

To see your rendered results with a live-reload experience, require the namespace notespace.v2.live-reload too. This will setup a live-reload server using Ring and Mirador and will open a browser showing the rendered data.

To compute and render the whole notespace, save the file and call:

(notespace.v2.note/compute-this-notespace!)

To compute and rerender a certain note, save the file and call:

(notespace.v2.note/compute-note-at-line! line)

where line is one of the lines of the file that are taken by that note.

The notespace library is still experimental. In the (not unlikely) case where something breaks, our current recommendation to reset the system's state.

(notespace.v2.note/reset-state!)

Soon things will be more robust.

Sometimes, the live-reload stops happening. A browser refresh sometimes fixes that.

Editor integration.

It is handy to be able to invoke the API functions using commands (and keybindings) of your editor. All you need is to figure out how to make your editor call Clojure functions and pass them the current line of the cursor.

In Emacs, one may do this using the following Elisp code:

(defun notespace/compute-note-at-this-line ()
  (interactive)
  (save-buffer)
  (cider-interactive-eval
   (concat "(notespace.v2.note/compute-note-at-line! "
           (number-to-string (count-lines 1 (point)))
           ")")
   (cider-interactive-eval-handler nil (point))
   nil
   nil)))

(defun notespace/compute-this-notespace ()
  (interactive)
  (save-buffer)
  (cider-interactive-eval
   "(notespace.v2.note/compute-this-notespace!)"
   (cider-interactive-eval-handler nil (point))
   nil
   nil)

Note kinds

We can have all kinds of different notes. The different kinds behave differently when rendered.

This one is a note of kind :md. When rendered, it renders as markdown and does not show the source string.

The following is a 'regular' note, of kind :code. When renders, it shows both the source code and the printed return value.

The following is a note of kind :void. It shows the source, but does not show the output.

The following is a note of kind :hiccup. It does not show the source, and renders the return value as hiccup.

Sometimes, we may want to render things as markdown or hiccup, but do want to see the source too. The following two kinds of notes are useful in those cases.

This is a note of kind :as-md. Shows the source, renders as markdown.

The following is a note of kind :as-hiccup. Shows the source, renders as hiccup.

Here is the summary of the note kinds we mentioned:

Labels

In the definition of the following note, we begin with a keyword: :label-example. This keyword is called the label of the note, and it is not rendered. It creates a link to that note from the table-of-contents.

Tables

It may be handy to render data in interactive tables. We have some auxiliary functions to render this using the DataTables JS library.

Graphics

Graphics can be rendered as hiccup. Here is an example using SVG.

Vega(-lite) plots

Vega or Vega-lite plots can be converted to hiccup and then rendered.

Currently we use darkstar for rendering vega/vega-lite to svg. This is work in progress. The API may change, and eventually we want to support interactive plots using vega.js.

Images

Here is a basic example of how one can include image files in a notespace. In the future we want to provide some less verbose ways to do it.

Tests

One may use the check function to create tests using arbitrary functions.