Allow key '{git-commit}' for source URIs

In source URIs the key '{git-commit}' is replaced with the Git commit
id of the repository.

See weavejester#168

README.md

@@ -211,11 +211,12 @@ to the function's source file in the documentation, you can set the
 
 The URI is a template that may contain the following keys:
 
-* `{filepath}`  - the file path from the root of the repository
-* `{basename}`  - the basename of the file
-* `{classpath}` - the relative path of the file within the source directory
-* `{line}`      - the line number of the source file
-* `{version}`   - the version of the project
+* `{filepath}`   - the file path from the root of the repository
+* `{basename}`   - the basename of the file
+* `{classpath}   - the relative path of the file within the source directory
+* `{line}`       - the line number of the source file
+* `{version}`    - the version of the project
+* `{git-commit}` - the Git commit id of the repository
 
 You can also assign different URI templates to different paths of your
 source tree. This is particularly useful for created source links from

codox/src/codox/main.clj

@@ -1,7 +1,9 @@
 (ns codox.main
   "Main namespace for generating documentation"
   (:use [codox.utils :only (add-source-paths)])
-  (:require [codox.reader.clojure :as clj]
+  (:require [clojure.string :as str]
+            [clojure.java.shell :as shell]
+            [codox.reader.clojure :as clj]
             [codox.reader.plaintext :as text]))
 
 (defn- writer [{:keys [writer]}]
@@ -91,17 +93,25 @@
                                (apply text/read-documents)
                                (sort-by :name))))
 
+(defn git-commit [dir]
+  (let [{:keys [out exit] :as result} (shell/sh "git" "rev-parse" "HEAD" :dir dir)]
+    (when ((complement zero?) exit)
+      (throw (ex-info "Error getting git commit" result)))
+    (str/trim out)))
+
 (def defaults
-  {:language     :clojure
-   :root-path    (System/getProperty "user.dir")
-   :output-path  "target/doc"
-   :source-paths ["src"]
-   :doc-paths    ["doc"]
-   :doc-files    :all
-   :namespaces   :all
-   :exclude-vars #"^(map)?->\p{Upper}"
-   :metadata     {}
-   :themes       [:default]})
+  (let [root-path (System/getProperty "user.dir")]
+    {:language     :clojure
+     :root-path    root-path
+     :output-path  "target/doc"
+     :source-paths ["src"]
+     :doc-paths    ["doc"]
+     :doc-files    :all
+     :namespaces   :all
+     :exclude-vars #"^(map)?->\p{Upper}"
+     :metadata     {}
+     :themes       [:default]
+     :git-commit   (delay (git-commit root-path))}))
 
 (defn generate-docs
   "Generate documentation from source files."

codox/src/codox/writer/html.clj

@@ -151,11 +151,14 @@
   (second (re-find #"/([^/]+?)$" path)))
 
 (defn- var-source-uri
-  [{:keys [source-uri version]}
+  [{:keys [source-uri version git-commit]}
    {:keys [path file line]}]
   (let [path (util/uri-path path)
-        uri  (if (map? source-uri) (get-source-uri source-uri path) source-uri)]
-    (-> uri
+        uri  (if (map? source-uri) (get-source-uri source-uri path) source-uri)
+        gc   "{git-commit}"
+        uri* (cond-> uri
+               (and (string? uri) (.contains uri gc)) (str/replace gc @git-commit))]
+    (-> uri*
         (str/replace "{filepath}"  path)
         (str/replace "{classpath}" (util/uri-path file))
         (str/replace "{basename}"  (uri-basename path))

example/build.boot

@@ -11,7 +11,7 @@
       :name "Example Project"
       :description "FIXME: write description"
       :version "1.0.0"
-      :source-uri "https://github.com/weavejester/codox/blob/{version}/codox.example/{filepath}#L{basename}-{line}"
+      :source-uri "https://github.com/weavejester/codox/blob/{git-commit}/example/{filepath}#L{basename}-{line}"
       :exclude-vars #"foo.*"
       :themes [[:test {:test-message "Test! Test! "}]])
     (target)))

example/project.clj

@@ -14,7 +14,7 @@
    :doc-files ["doc/intro.md"
                "doc/formatting.md"]
    :source-uri
-   "https://github.com/weavejester/codox/blob/{version}/codox.example/{filepath}#L{basename}-{line}"
+   "https://github.com/weavejester/codox/blob/{git-commit}/example/{filepath}#L{basename}-{line}"
    :html
    {:transforms [[:head] [:prepend [:script "console.log('hello');"]]
                  [:head] [:append  [:script "console.log('world');"]]