Move the code that generates doc tests out from build.clj
to its own source runnable via main.
This isolates gen-doc-tests work to its own process
during the build.
I arbitrarily:
- chose 'build' as the folder for build helper sources
- namespaced our first build helper under 'honey.gen-doc-tests'
Tests will now always regenerate when:
- there is no last successful generation run
- OR when any docs, build files, or source files are newer than the
last successful generation run.
Resolves#290
**Build**
New commands:
- `gen-doc-tests` - only regenerates tests if stale,
use `clean` command to force regen
- `run-doc-tests` - calls gen-doc-tests then runs tests,
accepts the same parameters as run-tests.
Can specify `:platform`
- `:cljs` - run tests under ClojureScript
- otherwise Clojure where we can specify one of: `:1.9`
`:1.10` `:master`
I'm not sure if my use of the `:platform` parameter jives with
your `:aliases` parameter used for `run-tests`.
Can adjust if you like.
Example usages:
```shell
clojure -T:build gen-doc-tests
clojure -T:build run-doc-tests :platform :cljs
clojure -T:build run-doc-tests
clojure -T:build run-doc-tests :platform :1.10
```
The `ci` command has been updated to generate and run doc tests for same
platforms as unit tests.
**Articles**
In addition to `README.md`, now testing doc blocks in all articles
under `doc` dir excepting `doc/operator-reference.md` which does not
have any runnable code blocks.
**Skipped**
Any code block that is intentionally not runnable has been marked to be
skipped via: `<!-- :test-doc-blocks/skip -->`.
**Consistency**
I noticed that some code blocks use REPL syntax:
```Clojure
user=> (+ 1 2 3)
6
```
and others use editor syntax:
```Clojure
(+ 1 2 3)
;;=> 6
```
some places also omit the comment for editor style:
```Clojure
(+ 1 2 3)
=> 6
```
All of this is just fine with test-doc-blocks.
I left the inconsistency as is, but can make a pass for consistency upon
request.
**HoneySQL state**
I noticed a code block that set the sql dialect was affecting other
tests. I simply restored the dialect to the default at the end of the
code block.
**Un-tweaked output**
Some code blocks had string output hand-tweaked for readability.
These have been adjusted to instead use `sql/format`'s `:pretty` option.
In some cases the output is not as readable as the hand-tweaked version.
I humbly suggest that perhaps `:pretty` output could perhaps be
improved (instead of having test-doc-blocks somehow adapt).
**Corrections**
There were very few code blocks that required fixing due to incorrect
output/code. Please review the diffs carefully to make sure all is as
expected.
**refer-clojure :excludes**
Not currently supported for test-doc-blocks, not a real issue for
Clojure, we'll see warnings under Clojure, but that's probably ok.
But I might actually need it for ClojureScript.
I was finding that `for` did not get overridden by our helper
`:refer` in CloureScript.
Will add proper support to test-doc-blocks but in the short-term,
will use `h/for`.
**ns requires adjustments**
Any specific case of `(ns my-ns (require [my-require :as a]))` is now
the REPL friendly `(require '[my-require :as a])`
Any missing required `requires` were added.
The HoneySQL docs seem to encourage the use of referred vars for
helpers. Although this has the con of overlaps with Clojure core vars,
it is also convenient for Clojure when using `:refer :all`.
**ClojureScript :refer**
ClojureScript does not support `:refer :all` and each var must be
specified in place of `:all`.
I have adjusted examples accordingly to work with both Clojure and
ClojureScript.
