Merge pull request #67 from vollcheck/documentation-overhaul

Documentation overhaul

resources/md/database.md

@@ -52,7 +52,7 @@ helper functions:
 
 ### SQL Queries
 
-SQL queries are parsed by HugSQL as defined in your `system.edn` and `resources/queries.sql` file by default. You 
+SQL queries are parsed by HugSQL as defined in your `system.edn` and `resources/queries.sql` file by default. You
 can update the filename to indicate a different path, e.g. `"sql/queries.sql"`.
 
 ```clojure
@@ -99,23 +99,39 @@ To run queries in a transaction you have to use `next.jdbc/with-transaction` as
     (query-fn tx :get-user-by-id {:id "foo"})))
 ```
 
-Note that you must use `tx` connection created by `with-transaction` in order for the query to be considered within the scope of the transaction. Please see official [nex.jdbc](https://github.com/seancorfield/next-jdbc/blob/develop/doc/transactions.md) documentation on transactions for further examples.
+Note that you must use `tx` connection created by `with-transaction` in order for the query to be considered within the scope of the transaction. Please see official [next.jdbc](https://github.com/seancorfield/next-jdbc/blob/develop/doc/transactions.md) documentation on transactions for further examples.
 
 For reference, here is the full definition from the Kit SQL edge:
 
 ```clojure
-(defmethod ig/init-key :db.sql/query-fn
-  [_ {:keys [conn options filename]
-      :or   {options {}}}]
-  (let [queries (conman/bind-connection-map conn options filename)]
+(defn queries-dev [load-queries]
+  (fn
+    ([query params]
+     (conman/query (load-queries) query params))
+    ([conn query params & opts]
+     (conman/query conn (load-queries) query params opts))))
+
+(defn queries-prod [load-queries]
+  (let [queries (load-queries)]
     (fn
       ([query params]
        (conman/query queries query params))
       ([conn query params & opts]
-       (apply conman/query conn queries query params opts)))))
+       (conman/query conn queries query params opts)))))
+
+(defmethod ig/init-key :db.sql/query-fn
+  [_ {:keys [conn options filename filenames env]
+      :or   {options {}}}]
+  (let [filenames (or filenames [filename])
+        load-queries #(apply conman/bind-connection-map conn options filenames)]
+    (with-meta
+      (if (= env :dev)
+        (queries-dev load-queries)
+        (queries-prod load-queries))
+      {:mtimes (mapv ig-utils/last-modified filenames)})))
 ```
 
-As you can see, the two-arity `query-fn` uses the database that you pass in the initial system configuration. However, the three plus-arity variant allows you to pass in a custom connection, allowing for SQL transactions.
+As you can see, the two-arity `query-fn` uses the database that you pass in the initial system configuration. However, the three plus-arity variant allows you to pass in a custom connection, allowing for SQL transactions. Definition above also allows Kit to reload queries source (be it single or multiple files) automatically if you operate on the `:dev` environment - for non-dev profile it would be loaded only once.
 
 
 ### Working with HugSQL
@@ -159,7 +175,7 @@ The following code illustrates how to use `hugsql.core/hugsql-command-fn` multim
 
 ```clojure
 
-(defn log-sqlvec [sqlvec] 
+(defn log-sqlvec [sqlvec]
   (log/info (->> sqlvec
                  (map #(clojure.string/replace (or % "") #"\n" ""))
                  (clojure.string/join " ; "))))

resources/md/kit-hato.md

@@ -2,7 +2,7 @@
 
 ### :http.client/hato
 
-Component that creates a [hato](https://github.com/gnarroway/hato) HTTP client for use throughout your application. 
+Component that creates a [hato](https://github.com/gnarroway/hato) HTTP client for use throughout your application.
 
 For example, you may configure it as follows in your `system.edn`
 
@@ -37,9 +37,8 @@ Now you can use this component throughout the application, e.g.
       :body
       (http-response/ok)))
 
-(defn api-routes [base-path]
-  [base-path
-   ["/swagger.json"
+(defn api-routes [_opts]
+  [["/swagger.json"
     {:get {:no-doc  true
            :swagger {:info {:title " API"}}
            :handler (swagger/create-swagger-handler)}}]
@@ -50,4 +49,4 @@ Now you can use this component throughout the application, e.g.
     {:post auth0-call}]])
 ```
 
-`http.client/hato` is derived from `http/client`. This is useful should you want to extend behaviour for multiple HTTP clients and want to apply the same logic across all of them.
+`http.client/hato` is derived from `http/client`. This is useful should you want to extend behaviour for multiple HTTP clients and want to apply the same logic across all of them.

resources/md/kit-sql-conman.md

@@ -14,7 +14,7 @@ It might be useful if you need to create transactions to reference the connectio
 Sample configuration:
 
 ```clojure
-:db.sql/connection 
+:db.sql/connection
 #profile {:prod {:jdbc-url   #env JDBC_URL
                  :init-size  1
                  :min-idle   1
@@ -36,7 +36,8 @@ Sample configuration:
 :db.sql/query-fn
  {:conn     #ig/ref :db.sql/connection
   :options  {}
-  :filename "queries.sql"}
+  :filename "queries.sql"
+  :env #ig/ref :system/env}
 ```
 
 Sample configuration with multiple query files:
@@ -45,5 +46,6 @@ Sample configuration with multiple query files:
 :db.sql/query-fn
  {:conn     #ig/ref :db.sql/connection
   :options  {}
-  :filenames ["queries.sql" "other-queries.sql"]}
+  :filenames ["queries.sql" "other-queries.sql"]
+  :env #ig/ref :system/env}
 ```

resources/md/learning_clojure.md

@@ -3,15 +3,14 @@ This section provides links to online resources, books, and development environm
 ### Online Clojure Guides
 
 * [Clojure Distilled](http://yogthos.github.io/ClojureDistilled.html) - introduction to core Clojure concepts
-* [Clojure - Functional Programming for the JVM](http://java.ociweb.com/mark/clojure/article.html) - a detailed Clojure primer aimed at Java developers
+* [Clojure - Functional Programming for the JVM](https://objectcomputing.com/resources/publications/sett/march-2009-core-functional-programming-for-the-jvm) - a detailed Clojure primer aimed at Java developers
 * [Clojure for the Brave and True](http://www.braveclojure.com/) - an excellent and humorous introduction to the language
 * [Clojure Documentation](http://clojure-doc.org/) - a collection of Clojure guides and tutorials
-* [4Clojure](http://www.4clojure.com/) - a site for practicing Clojure by solving interactive problems
+* [4Clojure](https://4clojure.oxal.com/) - a site for practicing Clojure by solving interactive problems
 * [ClojureScript in 15 minutes](https://github.com/shaunlebron/ClojureScript-Syntax-in-15-minutes) - concise guide to ClojureScript
 
 ### Clojure Reference
 
-* [Grimoire API reference](http://conj.io/)
 * [Clojure cheatsheet](http://clojure.org/cheatsheet)
 * [Clojure style guide](https://github.com/bbatsov/clojure-style-guide)
 * [Clojure by Example](https://kimh.github.io/clojure-by-example/)
@@ -24,15 +23,15 @@ This section provides links to online resources, books, and development environm
 * [Clojure in Action](http://www.amazon.com/Clojure-Action-Amit-Rathore/dp/1935182595/)
 * [The Joy of Clojure: Thinking the Clojure Way](http://www.amazon.com/The-Joy-Clojure-Thinking-Way/dp/1935182641/ref=pd_bxgy_b_img_y)
 * [Practical Clojure](http://www.apress.com/9781430272311)
-* [Web Development with Clojure](https://pragprog.com/book/dswdcloj2/web-development-with-clojure-second-edition)
+* [Web Development with Clojure](https://www.oreilly.com/library/view/web-development-with/9781680508833)
 * [Clojure Web Development Essentials](https://www.packtpub.com/application-development/clojure-web-development-essentials)
 
 
 ### IDE Support
 
 There is a number of IDEs to choose from for Clojure development.
 
-* [Emacs](http://clojure-doc.org/articles/tutorials/emacs.html) - currently the most popular IDE for Clojure.
+* [Emacs](http://clojure.org/guides/editors#_emacs_most_popular_most_customizable) - currently the most popular IDE for Clojure.
 * [IntelliJ](http://www.jetbrains.com/idea/download/) - IntelliJ provides an excellent Clojure development environment via the [Cursive plugin](http://cursiveclojure.com/).
 * [Visual Studio Code](https://code.visualstudio.com/) - Extensible editor featuring the [Calva](https://github.com/BetterThanTomorrow/calva) plugin available from the editor Plugin Marketplace.
 * [Vim Iced](https://github.com/liquidz/vim-iced) - Full-featured Clojure editing for Vim.