Merge pull request #170 from UweHubert/master

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

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

@@ -150,17 +150,23 @@
 (defn- uri-basename [path]
   (second (re-find #"/([^/]+?)$" path)))
 
+(defn- force-replace [^String s match replacement]
+  (if (.contains s match)
+    (str/replace s match (force replacement))
+    s))
+
 (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
-        (str/replace "{filepath}"  path)
-        (str/replace "{classpath}" (util/uri-path file))
-        (str/replace "{basename}"  (uri-basename path))
-        (str/replace "{line}"      (str line))
-        (str/replace "{version}"   version))))
+        (str/replace   "{filepath}"   path)
+        (str/replace   "{classpath}"  (util/uri-path file))
+        (str/replace   "{basename}"   (uri-basename path))
+        (str/replace   "{line}"       (str line))
+        (str/replace   "{version}"    version)
+        (force-replace "{git-commit}" git-commit))))
 
 (defn- split-ns [namespace]
   (str/split (str namespace) #"\."))

example/project.clj

@@ -35,4 +35,8 @@
             :source-paths ^:replace ["src-typed/clojure"]}
    :no-src {:codox ^:replace {}}
    :no-doc {:codox {:doc-paths ^:replace []}}
-   :1.7    {:dependencies [[org.clojure/clojure "1.7.0"]]}})
+   :1.7    {:dependencies [[org.clojure/clojure "1.7.0"]]}
+   :git-commit
+   {:codox
+    {:source-uri
+     "https://github.com/weavejester/codox/blob/{git-commit}/example/{filepath}#L{basename}-{line}"}}})