This page is not created by, affiliated with, or supported by Slack Technologies, Inc.
2018-06-26
Channels
- # adventofcode (2)
- # beginners (69)
- # boot (37)
- # cider (6)
- # clara (31)
- # cljs-dev (75)
- # cljsrn (5)
- # clojure (72)
- # clojure-dev (7)
- # clojure-italy (11)
- # clojure-nl (8)
- # clojure-russia (2)
- # clojure-spec (56)
- # clojure-uk (54)
- # clojure-za (1)
- # clojurescript (156)
- # cursive (2)
- # datomic (34)
- # emacs (1)
- # fulcro (227)
- # hoplon (74)
- # jobs (1)
- # jobs-discuss (16)
- # leiningen (5)
- # lumo (17)
- # off-topic (9)
- # om (3)
- # onyx (10)
- # other-languages (1)
- # portkey (2)
- # re-frame (2)
- # reagent (36)
- # reitit (1)
- # remote-jobs (1)
- # ring-swagger (8)
- # shadow-cljs (85)
- # slack-help (2)
- # spacemacs (6)
- # specter (3)
- # sql (17)
- # test-check (15)
- # tools-deps (80)
Any suggestions how to write testable documentation prose with SQL examples, in way that fits clojure workflow? So that in the middle of a explanations there's a SQL query, and answer, and when running tests or something, you could compare the written docs to actual results. Or perhaps it just inserts the results into documentation. I'm currently using HugSQL, if that matters.
So far I've been doing the minimum by having markdown files (that bitbucket will render) with code snippets, but I'm getting worried that my examples are drifting from reality.
I'm considering switching to rendering Hugsql vecs, but that loses the pretty formatting I have in the somewhat long snippets
Or maybe just writing clojure, with the SQL in strings, and then rendering into md or something else from those
I'd like the document to be readable without clojure knowledge, so that people who know the backend SQL services could see how this program is combining the different data sources
Since you want to render your original SQL to the documentation, you can probably use map-of-db-fns-from-string
: http://layerware.github.io/hugsql/hugsql.core.html#var-map-of-db-fns-from-string
HugSQL doesn't keep your original SQL statement after compiling it, so you'll need to keep it as a string and use the HugSQL *-from-string
functions. map-of-db-fns-from-string
is an easy way to pass around a map of fns instead of defining them directly in your namespace. The SQL statement will need to have a HugSQL-flavored SQL with -- :name my-fn :? :*
comments.
But so far I don't know if it makes more sense to have code snippets inside text document, or text snippets inside code
Sounds like you want "literate programming" for your SQL files @U8ZQ1J1RR?
I've had some success with https://github.com/gdeer81/marginalia as far as Clojure code is concerned but I don't know what you'd need to do for separate .sql
files with HugSQL.
For one of our recent new projects with some highly complex business rules, we used Marginalia and wrote everything out as prose in .clj
files with just stub functions (and generated docs for sign-off by the product owner), and then used TDD to gradually build out the code -- some of which replaced prose and some of which still had the prose as inline comments.
That said, over time, the code still drifted away from the prose as changes in requirements came in. I think it's a truly hard problem to solve, long-term.
(and partly why "literate programming" really hasn't caught on)