Fork me on GitHub
#sql
<
2018-06-26
>
Hukka11:06:56

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.

Hukka11:06:47

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.

Hukka11:06:56

I'm considering switching to rendering Hugsql vecs, but that loses the pretty formatting I have in the somewhat long snippets

Hukka11:06:08

Or maybe just writing clojure, with the SQL in strings, and then rendering into md or something else from those

Hukka11:06:25

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

curtis.summers12:06:17

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

curtis.summers12:06:52

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.

Hukka12:06:54

Yeah, that would be the way to go from clj to rendered document

Hukka12:06:28

But so far I don't know if it makes more sense to have code snippets inside text document, or text snippets inside code

Hukka12:06:40

Code in text could use something like endophile, I guess

seancorfield17:06:15

Sounds like you want "literate programming" for your SQL files @U8ZQ1J1RR?

seancorfield17:06:11

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.

seancorfield17:06:22

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.

seancorfield17:06:03

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.

seancorfield17:06:15

(and partly why "literate programming" really hasn't caught on)

Hukka18:06:16

It does, indeed, though I don't require the free reordering of code (which isn't in marginalia anyway). And for now, only for the part that's specifically documentation, not the whole codebase. But I have been thinking about the same problem with clojure and polyglot code too.

Hukka18:06:21

I suppose the problem is pretty much the same as tests, though there's not even a bit of automated support to verify that docs and code match. So you would need to rely on code review (as simply relying on developer discipline in a vacuum will not work)