Add finding docs functionality from ClojureDocs

Author: liquidz

CHANGELOG.md

@@ -9,6 +9,7 @@
 * [#46](https://github.com/clojure-emacs/orchard/pull/46): [Inspector] Show fields inherited from superclasses when rendering raw objects.
 * [#47](https://github.com/clojure-emacs/orchard/pull/46): [Java] Cache class-info for editable Java classes.
 * [#51](https://github.com/clojure-emacs/orchard/issues/51): Add basic xref functionality in `orchard.xref`.
+* [#64](https://github.com/clojure-emacs/orchard/issues/64): Add finding docs functionality from ClojureDocs in `orchard.clojuredocs`.
 
 ### Changes
 

Makefile

@@ -11,10 +11,13 @@ TEST_SELECTOR := :java$(JAVA_VERSION)
 
 TEST_PROFILES := +test
 
-test:
+test-resources/clojuredocs/export.edn:
+	curl -o $@ https://clojuredocs-edn.netlify.com/export.edn
+
+test: test-resources/clojuredocs/export.edn
 	lein with-profile +$(VERSION),$(TEST_PROFILES) test $(TEST_SELECTOR)
 
-test-watch:
+test-watch: test-resources/clojuredocs/export.edn
 	lein with-profile +$(VERSION),$(TEST_PROFILES) test-refresh $(TEST_SELECTOR)
 
 # Eastwood can't handle orchard.java.legacy-parser at the moment, because

src/orchard/clojuredocs.clj

@@ -0,0 +1,35 @@
+(ns orchard.clojuredocs
+  "Find docs from ClojureDocs and retrieve the result as a map."
+  {:author "Masashi Iizuka"}
+  (:require
+   [clojure.edn :as edn]))
+
+(def cache (atom {}))
+
+(defn- map-from-key [f coll]
+  (reduce #(assoc %1 (f %2) %2) {} coll))
+
+(defn update-documents-cache!
+  "Load exported documents file from ClojureDocs, and store it as a cache.
+  A EDN format file is expected to the `export-edn-file` argument.
+  (e.g. https://clojuredocs-edn.netlify.com/export.edn)"
+  {:added "0.5.0"}
+  [export-edn-file]
+  (let [docs (-> export-edn-file slurp edn/read-string)]
+    (->> (:vars docs)
+         (group-by #(:ns %))
+         (reduce-kv #(assoc %1 %2 (map-from-key :name %3)) {})
+         (hash-map export-edn-file)
+         (reset! cache))
+    true))
+
+(defn find-document
+  "Find a document matching to ns-name and var-name from cached documents.
+  If there are no cached documents corresponding to `export-edn-file`, cache will be updated.
+
+  Return nil if there is no matching document."
+  {:added "0.5.0"}
+  [export-edn-file ns-name var-name]
+  (when-not (contains? @cache export-edn-file)
+    (update-documents-cache! export-edn-file))
+  (get-in @cache [export-edn-file ns-name var-name]))

test-resources/clojuredocs/export.edn

@@ -0,0 +1,26 @@
+(ns orchard.clojuredocs-test
+  (:require
+   [clojure.java.io :as io]
+   [clojure.test :as test :refer [deftest is testing]]
+   [orchard.clojuredocs :as docs]))
+
+(def ^:private test-edn-file
+  (io/resource "clojuredocs/export.edn"))
+
+(deftest update-documents-cache!-test
+  (reset! docs/cache {})
+  (is (not (contains? @docs/cache test-edn-file)))
+
+  (is (true? (docs/update-documents-cache! test-edn-file)))
+  (is (contains? @docs/cache test-edn-file))
+  (is (contains? (get @docs/cache test-edn-file) "clojure.core")))
+
+(deftest find-document-test
+  (testing "find existing document"
+    (let [result (docs/find-document test-edn-file "clojure.core" "first")]
+      (is (map? result))
+      (is (every? #(contains? result %)
+                  [:arglists :doc :examples :name :notes :ns :see-alsos]))))
+
+  (testing "find non-existing document"
+    (is (nil? (docs/find-document test-edn-file "non-existing-ns" "non-existing-var")))))

test/orchard/clojuredocs_test.clj

@@ -1,12 +1,15 @@
 (ns orchard.resource-test
   (:require
-   [clojure.test :refer [deftest testing is]]
+   [clojure.string :as str]
+   [clojure.test :refer [deftest is testing]]
    [orchard.resource :as resource]))
 
 (deftest resource-path-tuple-test
   (is (nil? (resource/resource-path-tuple "jar:file:fake.jar!/fake/file.clj"))))
 
 (deftest project-resources-test
   (testing "get the correct resources for the orchard project"
-    (is (= "see-also.edn" (-> (resource/project-resources) first :relpath)))
-    (is (= java.net.URL (-> (resource/project-resources) first :url class)))))
+    (let [resources (->> (resource/project-resources)
+                         (remove #(str/ends-with? (.getAbsolutePath (:root %)) "test-resources")))]
+      (is (= "see-also.edn" (-> resources first :relpath)))
+      (is (= java.net.URL (-> resources first :url class))))))