Add a middleware to find docs from ClojureDocs

Author: liquidz

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 * [#605](https://github.com/clojure-emacs/cider-nrepl/pull/605): Added a option for filtering vars to the ns-vars middleware.
 * Added `xref` middleware providing `fn-deps` and `fn-refs` ops.
+* [#628](https://github.com/clojure-emacs/cider-nrepl/pull/628): Added `clojuredocs` middleware providing `clojuredocs-lookup` and `clojuredocs-refresh-cache` ops.
 
 ### Bugs fixed
 

Makefile

@@ -6,13 +6,16 @@ export CLOVERAGE_VERSION = 1.0.13
 JAVA_VERSION = $(shell lein with-profile +sysutils \
                        sysutils :java-version-simple | cut -d " " -f 2)
 
+test/resources/cider/nrepl/clojuredocs/export.edn:
+	curl -o $@ https://clojuredocs-edn.netlify.com/export.edn
+
 .inline-deps:
 	lein inline-deps
 	touch .inline-deps
 
 inline-deps: .inline-deps
 
-test: .inline-deps
+test: .inline-deps test/resources/cider/nrepl/clojuredocs/export.edn
 	lein with-profile +$(CLOJURE_VERSION),+test,+plugin.mranderson/config test
 
 eastwood:

README.md

@@ -122,6 +122,7 @@ under `:repl-options`.
 :repl-options {:nrepl-middleware
                  [cider.nrepl/wrap-apropos
                   cider.nrepl/wrap-classpath
+                  cider.nrepl/wrap-clojuredocs
                   cider.nrepl/wrap-complete
                   cider.nrepl/wrap-debug
                   cider.nrepl/wrap-format
@@ -261,6 +262,7 @@ Middleware        | Op(s)      | Description
 ------------------|------------|---------------------------------------------------------
 `wrap-apropos`    | `apropos`  | Pattern search for symbols and documentation.
 `wrap-classpath`  | `classpath` | Java classpath.
+`wrap-clojuredocs`| `clojuredocs-lookup/clojuredocs-refresh-cache` | Look up ClojureDocs.
 `wrap-complete`   | `complete` | Simple completion. Supports both Clojure & ClojureScript.
 `wrap-debug`      | `init-debugger/debug-input` | Establish a channel for `cider-debug` commands, use it to get debug input, and also wrap the eval op.
 `wrap-format`     | `format-(code/edn)` | Code and data formatting.

src/cider/nrepl.clj

@@ -478,12 +478,28 @@
               :returns {"fn-deps" "A list of function deps."
                         "status" "done"}}}})
 
+(def-wrapper wrap-clojuredocs cider.nrepl.middleware.clojuredocs/handle-clojuredocs
+  {:doc "Middleware to find a documents from ClojureDocs."
+   :handles {"clojuredocs-refresh-cache"
+             {:doc "Reload exported documents file from ClojureDocs, and store it as a cache."
+              :requires {}
+              :optional {"export-edn-url" "EDN file URL exported from ClojureDocs. Defaults to \"https://clojuredocs-edn.netlify.com/export.edn\"."}
+              :returns {"status" "\"ok\" if reloading was successful"}}
+             "clojuredocs-lookup"
+             {:doc "Return a map of information in ClojureDocs."
+              :requires {"ns" "The namespace where `symbol` is define."
+                         "symbol" "The symbol to lookup."}
+              :optional {"export-edn-url" "EDN file URL exported from ClojureDocs. Defaults to \"https://clojuredocs-edn.netlify.com/export.edn\"."}
+              :returns {"clojuredocs" "A map of information in ClojureDocs."
+                        "status" "\"no-document\" if there is no document matching to `ns` and `symbol`."}}}})
+
 ;;; Cider's Handler
 
 (def cider-middleware
   "A vector of all CIDER middleware."
   `[wrap-apropos
     wrap-classpath
+    wrap-clojuredocs
     wrap-complete
     wrap-debug
     wrap-enlighten

src/cider/nrepl/middleware/clojuredocs.clj

@@ -0,0 +1,24 @@
+(ns cider.nrepl.middleware.clojuredocs
+  (:require
+   [cider.nrepl.middleware.util.error-handling :refer [with-safe-transport]]
+   [orchard.clojuredocs :as docs]
+   [orchard.misc :as misc]))
+
+(defn- clojuredocs-lookup-reply [{:keys [export-edn-url ns symbol]}]
+  (if-let [doc (if export-edn-url
+                 (docs/find-doc ns symbol export-edn-url)
+                 (docs/find-doc ns symbol))]
+    {:clojuredocs (misc/transform-value doc)}
+    {:status :no-document}))
+
+(defn clojuredocs-refresh-cache-reply [{:keys [export-edn-url]}]
+  (docs/clean-cache!)
+  (if export-edn-url
+    (docs/load-cache! export-edn-url)
+    (docs/load-cache!))
+  {:status :ok})
+
+(defn handle-clojuredocs [handler msg]
+  (with-safe-transport handler msg
+    "clojuredocs-refresh-cache" clojuredocs-refresh-cache-reply
+    "clojuredocs-lookup" clojuredocs-lookup-reply))

src/cider_nrepl/plugin.clj

@@ -67,6 +67,7 @@
                      ;; requiring `cider.nrepl`).
                      '[cider.nrepl/wrap-apropos
                        cider.nrepl/wrap-classpath
+                       cider.nrepl/wrap-clojuredocs
                        cider.nrepl/wrap-complete
                        cider.nrepl/wrap-debug
                        cider.nrepl/wrap-enlighten

test/clj/cider/nrepl/middleware/clojuredocs_test.clj

@@ -0,0 +1,40 @@
+(ns cider.nrepl.middleware.clojuredocs-test
+  (:require
+   [cider.nrepl.test-session :as session]
+   [clojure.string :as str]
+   [clojure.test :refer :all]))
+
+(def ^:private test-url "test/resources/cider/nrepl/clojuredocs/export.edn")
+
+(use-fixtures :each session/session-fixture)
+
+(deftest clojuredocs-refresh-cache-integration-test
+  (testing "Invalid URL"
+    (let [response (session/message {:op "clojuredocs-refresh-cache"
+                                     :export-edn-url "/non-existing.edn"})]
+      (is (contains? (:status response) "clojuredocs-refresh-cache-error"))
+      (is (not (str/blank? (:err response))))))
+
+  (testing "Valid URL"
+    (let [response (session/message {:op "clojuredocs-refresh-cache"
+                                     :export-edn-url test-url})]
+      (is (contains? (:status response) "ok")))))
+
+(deftest clojuredocs-lookup-integration-test
+  (testing "Find not existing document"
+    (let [response (session/message {:op "clojuredocs-lookup"
+                                     :ns "non-existing"
+                                     :symbol "non-existing"
+                                     :export-edn-url test-url})]
+      (is (contains? (:status response) "no-document"))))
+
+  (testing "Find existing document"
+    (let [response (session/message {:op "clojuredocs-lookup"
+                                     :ns "clojure.core"
+                                     :symbol "first"
+                                     :export-edn-url test-url})
+          doc (get response :clojuredocs {})]
+      (is (contains? (:status response) "done"))
+      (is (= "clojure.core" (:ns doc)))
+      (is (= "first" (:name doc)))
+      (is (every? #(contains? doc %) [:examples :see-alsos])))))

test/clj/cider/nrepl/plugin_test.clj

@@ -11,6 +11,7 @@
    {:nrepl-middleware
     '[cider.nrepl/wrap-apropos
       cider.nrepl/wrap-classpath
+      cider.nrepl/wrap-clojuredocs
       cider.nrepl/wrap-complete
       cider.nrepl/wrap-debug
       cider.nrepl/wrap-enlighten