Snippets

Snippet is a small example that shows how to use some Quil function. Each function should have at least one snippets. Snippets have two important goals:

1. Documentation. On quil.info/api snippets displayed under each function as example of how to use that function.
2. Testing. When releasing new version of Quil we run all snippets on clj and cljs to make sure that they don't throw any errors. Though at the moment we don't check visually whether snippets produce desired output as there are too many functions to check manually. Ideally we'd have visual automated tests at some point.

When adding/changing Quil function author should add/modify corresponding snippets.

Adding/modifying snippets

Snippets live in https://github.com/quil/quil/tree/master/src/cljc/quil/snippets folder. Structure of the folder follows category/subcategory of the functions. For example snippets for abs function which has :category "Math" :subcategory "Calculation" will be in the file math/calculation.cljc. Snippet for the abs function looks like the following:

(defsnippet abs
  "abs"
  {}

  (q/background 255)
  (q/fill 0)
  (q/text (str "(q/abs -1) = " (q/abs -1)) 10 20)
  (q/text (str "(q/abs -0.5) = " (q/abs -0.5)) 10 40))

Snippet is defined using defsnippet macro. Macro has documentation describing how to use it. Please note that comments in snippets should be added as (comment "hello world) instead of ;hello world so that they are not stripped by reader.

Testing snippets

To run clj test use the following command:

MANUAL=true lein test :only quil.snippet/quil_snippets_math_calculation_abs

Substituting match_calculation_abs with snippet's category_subcategory_name.

To run cljs use the following commands:

lein with-profile cljs-testing do cljsbuild once tests, ring server

It will compile cljs snippets to js and starts a http server. Open "Common Quil API tests", select your snippet and it should render it.

Running all snippets

TODO

Generate documention

Snippets are used in quil.info to provide examples how to use each function. During each Quil release we need to generate a snippets.clj file that contains info about all snippets. This file is later copied to quil-site as snippets-data-$QUIL_VERSION.clj. Here are the steps to generate the file:

1. Compile cljs code that will generate cljs versions of all snippets:

lein with-profile cljs-testing cljsbuild once snippets-generation

While compiling the file you might see an error "FileNotFoundException: snippets.clj (No such file or directory)". Ignore it, it caused by evaluation of different clj file.

2. Open snippets_generator.html and copy data from the text area to a snippets.clj file that you need to create in root of quil repo.

google-chrome dev-resources/utils/snippets_generator.html

3. Now generate clj versions of all snippets. Run lein repl and then:

(load-file "dev-resources/utils/snippets_generator.clj")

This script will append clj versions of snippets to the snippets.clj.

4. Now copy snippets.clj to snippets-data-$QUIL_VERSION.clj in quil-site folder.

It would be nice to automate this process of generating snippets data, but current approach is ok given we have to do it once per release.