Fork me on GitHub

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:


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.


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


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


Code in text could use something like endophile, I guess


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


I've had some success with 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)


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.


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)