Add ClojureDocs Command for examples to Rich Comments and to Output window

.vscode/settings.json

@@ -3,43 +3,22 @@
     "mochaExplorer.files": "src/extension-test/unit/**/*-test.ts",
     "mochaExplorer.require": "ts-node/register",
     "cSpell.words": [
-        "Batsov",
-        "Bozhidar",
-        "CLJSREPL",
-        "Calva's",
-        "Cognitect",
-        "Dedent",
-        "Docstring",
-        "FUBAR",
-        "Girardi",
-        "Hmmm",
-        "Insourcing",
-        "Jackin",
-        "Jackout",
-        "Libspec",
-        "Notespace",
-        "OVSX",
-        "Pseudoterminal",
-        "REBL",
-        "REPLs",
-        "Sdeps",
-        "Sexp",
-        "Sexpr",
-        "Sexps",
-        "Strömberg's",
-        "VSIX",
         "ahlbrecht",
         "alnum",
+        "Alsos",
         "analysing",
         "arglist",
         "arglists",
         "autoindent",
+        "Batsov",
         "bencode",
         "betterthantomorrow",
         "bhauman",
         "borkdude",
+        "Bozhidar",
         "brear",
         "calva",
+        "Calva's",
         "chmod",
         "cibuilds",
         "circleci",
@@ -49,14 +28,17 @@
         "cljfx",
         "cljify",
         "cljslib",
+        "CLJSREPL",
         "clojurians",
         "cmdline",
         "codeblock",
         "codehilite",
         "codelense",
+        "Cognitect",
         "cospaia",
         "debugable",
         "debugadapter",
+        "Dedent",
         "defproject",
         "defun",
         "deref",
@@ -65,12 +47,14 @@
         "devtool",
         "devtools",
         "docmirror",
+        "Docstring",
         "eckstein",
         "eldoc",
         "enablement",
         "enablements",
         "entrypoint",
         "errored",
+        "être",
         "eval",
         "evals",
         "falsesomething",
@@ -80,15 +64,21 @@
         "figwheel",
         "filipe",
         "fipp",
+        "FUBAR",
         "gifs",
+        "Girardi",
         "gsub",
         "hacky",
         "highlightning",
+        "Hmmm",
         "hopperdietzel",
         "howto",
         "inferer",
         "infoparser",
+        "Insourcing",
         "isequal",
+        "Jackin",
+        "Jackout",
         "janne",
         "jsify",
         "jszip",
@@ -99,17 +89,20 @@
         "lein",
         "leiningen",
         "lexing",
+        "Libspec",
         "luminus",
         "missmatch",
         "mkdir",
         "mkdocs",
         "nashorn",
         "niclas",
+        "Notespace",
         "nrepl",
         "ntqry",
         "ontype",
         "openjdk",
         "outdent",
+        "OVSX",
         "pageview",
         "paredit",
         "paren",
@@ -122,19 +115,27 @@
         "preinstall",
         "prepending",
         "prewatch",
+        "Pseudoterminal",
         "randr",
+        "REBL",
         "refactorings",
+        "REPLs",
         "reponame",
         "ringe",
         "sauvala",
         "sbin",
         "scaturro",
         "schäfer",
+        "Sdeps",
         "seqs",
+        "Sexp",
+        "Sexpr",
+        "Sexps",
         "sivertsen",
         "stacktraces",
         "stian",
         "strömberg",
+        "Strömberg's",
         "suitible",
         "terje",
         "togglemode",
@@ -148,10 +149,10 @@
         "visibles",
         "vsce",
         "vscodevim",
+        "VSIX",
         "webpack'ed",
         "webpacked",
         "xvfb",
-        "zprint",
-        "être"
+        "zprint"
     ]
 }

CHANGELOG.md

@@ -3,6 +3,7 @@
 Changes to Calva.
 
 ## [Unreleased]
+- [Include material from clojuredocs.org in function documentation](https://github.com/BetterThanTomorrow/calva/issues/689)
 - Fix: [Not able to escape read-line in the output window](https://github.com/BetterThanTomorrow/calva/issues/783)
 - Fix: [Some keyboard shortcuts missing the languageID check](https://github.com/BetterThanTomorrow/calva/issues/823)
 - Fix: [Formatting form with comma whitespace inserts 0 and places the cursor wrong](https://github.com/BetterThanTomorrow/calva/issues/1370)

docs/site/clojuredocs.md

@@ -0,0 +1,75 @@
+# ClojureDocs integration
+
+[clojuredocs.org](https://clojuredocs.org) is the goto place #1 for finding out more about Clojure core(-ish) functions, macros, etcetera. It contains the doc strings from the functions and adds crowd sourced examples of usage and see alsos. You can surf for quite long on that site without getting bored. 😄
+
+Calva integrates this information in two ways:
+
+1. Commands for requesting the ClojureDocs information for a symbol under the cursor:
+    * **Print clojuredocs.org examples to Rich Comment**, default keybinding: `ctrl+alt+r d`
+    * **Print clojuredocs.org examples to OutputWindow**, `ctrl+alt+o d`
+2. ClojureDocs information is included in the symbol lookup hovers, where each example has two buttons:
+    * **To Rich Comment**
+    * **To Output Window** 
+
+That means that if you just want to glance at the examples, you look in the hover. And when you want to bring the examples to the REPL to play with them, you can do so very easily.
+
+!!! Note "ClojureScript support"
+    ClojureDocs information is available both for Clojure and ClojureScript files. However, clojuredocs.org only keeps info for Clojure. Thus: _All information Calva shows about a symbol will be about the Clojure respresentation of that symbol._ (The symbol might not even exist in ClojureScript.)
+
+## ClojureDocs REPL Surfing
+
+Since the ClojureDocs information includes see-alsos, you can go for super interactive ClojureDocs surfing right in the file you are editing. Say you have this function:
+
+```clojure
+(defn trim-text
+  "Returns text without surrounding whitespace if not empty, otherwise nil"
+  [text]
+  (let [trimmed-text (clojure.string/trim text)]
+    (when-not (empty? trimmed-text)
+      trimmed-text)))
+```
+
+Then you hover on `when-not` and scroll down a bit in the hover:
+
+![when-not ClojureDocs Hover Example 1](images/clojuredocs-hover-when-not-example-1.png)
+
+That first example would be interesting to play with, right? Click **To Rich Comment** and you will get:
+
+```clojure
+(defn trim-text
+  "Returns text without surrounding whitespace if not empty, otherwise nil"
+  [text]
+  (let [trimmed-text (clojure.string/trim text)]
+    (when-not (empty? trimmed-text)
+      trimmed-text)))
+
+(comment
+  ;; = when-not - Example 1 = 
+
+  ;; build tuples over sets with the same cardinality 
+  (map
+   #(when-not (= %2 %3) [%1 %2 %3])
+   (iterate inc 0)   ; a lazy list of indecies
+   [:a :b :c]
+   [:a :a :a])
+  ;;=> (nil [1 :b :a] [2 :c :a])
+
+  ;; See also:
+  when
+  when-let
+  if
+  )
+```
+
+There you can evaluate the `(map ...)` form using `alt+enter`, modify it and evaluate again. You can also hover over `map`, `iterate`, or any of the ”See also:” symbols to find more fun examples to play with. And so on and so forth.
+
+See these two tweets for some videos of early versions of this functionality:
+
+* [Rich Comments surfing ClojureDocs Examples](https://twitter.com/pappapez/status/1452325865933746185)
+* [Clojuredocs in #Calva WIP 2: Hover examples -> RFC](https://twitter.com/pappapez/status/1452409528511762444)
+
+Please retweet!
+
+## Quirks
+
+Some of the ClojureDocs entries have text that is not really Clojure code, and sometimes even structural errors. This can break the structural integrity of your Clojure file. If you run into trouble trying to heal things, you can always use **Undo** until the Rich Comment is gone.

docs/site/output.md

@@ -10,13 +10,13 @@ The first prompt is from when the `clj` REPL is connected, the second when Calva
 
 ## Find the Output/REPL Window
 
-If you quickly want to open and switch to the output window there is the command **Calva: Show Output Window**, `ctrl+alt+c o`.
+If you quickly want to open and switch to the output window there is the command **Calva: Show Output Window**, `ctrl+alt+o o`.
 
 To sync the Output/REPL window namespace with the current file before switching, use the **Switch Namespace of the Output/REPL Window to Current Namespace** command, `ctrl+alt+c alt+n`.
 
 ## Find the File for the Current REPL Window Namespace
 
-When you are working from the Output/REPL window, and want to open the file that defines its current namespace, use the **Show File for the Current Output/REPL Window Namespace** command, `ctrl+alt+c o`.
+When you are working from the Output/REPL window, and want to open the file that defines its current namespace, use the **Show File for the Current Output/REPL Window Namespace** command, `ctrl+alt+o o`.
 
 !!! Note
     This also works for Clojure core and library namespaces.
@@ -37,7 +37,7 @@ The output window will print the defined var and then a new prompt reflecting th
 
 ![eval-results-1](images/howto/output/eval-results-1.png)
 
-If you then switch to the output window (`ctrl+alt+c o`), and enter this at the prompt:
+If you then switch to the output window (`ctrl+alt+o o`), and enter this at the prompt:
 
 ```clojure
 mount-target

mkdocs.yml

@@ -35,6 +35,7 @@ nav:
     - commands-top10.md
     - evaluation.md
     - rich-comments.md
+    - clojuredocs.md
     - output.md
     - formatting.md
     - paredit.md

package.json

@@ -1437,6 +1437,18 @@
                 "enablement": "calva:connected",
                 "category": "Calva"
             },
+            {
+                "command": "calva.printClojureDocsToOutputWindow",
+                "title": "Print clojuredocs.org examples to OutputWindow",
+                "enablement": "calva:connected",
+                "category": "Calva"
+            },
+            {
+                "command": "calva.printClojureDocsToRichComment",
+                "title": "Print clojuredocs.org examples to Rich Comment",
+                "enablement": "calva:connected",
+                "category": "Calva"
+            },
             {
                 "command": "calva.refactor.cleanNs",
                 "title": "Clean NS Form",
@@ -2047,12 +2059,12 @@
             },
             {
                 "command": "calva.showOutputWindow",
-                "key": "ctrl+alt+c o",
+                "key": "ctrl+alt+o o",
                 "when": "calva:keybindingsEnabled && calva:connected && !calva:outputWindowActive"
             },
             {
                 "command": "calva.showFileForOutputWindowNS",
-                "key": "ctrl+alt+c o",
+                "key": "ctrl+alt+o o",
                 "when": "calva:keybindingsEnabled && calva:connected && calva:outputWindowActive"
             },
             {
@@ -2081,6 +2093,16 @@
                 "key": "alt+down",
                 "when": "calva:keybindingsEnabled && editorLangId == clojure && calva:connected && calva:outputWindowActive"
             },
+            {
+                "command": "calva.printClojureDocsToOutputWindow",
+                "key": "ctrl+alt+o d",
+                "when": "calva:keybindingsEnabled && editorLangId == clojure && calva:connected"
+            },
+            {
+                "command": "calva.printClojureDocsToRichComment",
+                "key": "ctrl+alt+r d",
+                "when": "calva:keybindingsEnabled && editorLangId == clojure && calva:connected"
+            },
             {
                 "command": "calva.runCustomREPLCommand",
                 "key": "ctrl+alt+space enter",