Add jupyter-describe function for interactive inspect

jupyter-describe implements an interface (with completion) similar to
emacs builtin describe-function for interacting with jupyter kernels.

Closes emacs-jupyter#199

Author: non-Jedi

README.org

@@ -279,17 +279,18 @@ associate with the =current-buffer= and enable the minor mode
 =jupyter-repl-interaction-mode=. This minor mode populates the following
 keybindings for interacting with the REPL:
 
-| Key binding | Command                       |
-|-------------+-------------------------------|
-| =C-M-x=       | =jupyter-eval-defun=            |
-| =M-i=         | =jupyter-inspect-at-point=      |
-| =C-c C-b=     | =jupyter-eval-buffer=           |
-| =C-c C-c=     | =jupyter-eval-line-or-region=   |
-| =C-c C-i=     | =jupyter-repl-interrupt-kernel= |
-| =C-c C-r=     | =jupyter-repl-restart-kernel=   |
-| =C-c C-s=     | =jupyter-repl-scratch-buffer=   |
-| =C-c C-o=     | =jupyter-eval-remove-overlays=  |
-| =C-c M-:=     | =jupyter-eval-string=           |
+| Key binding | Command                         |
+|-------------+---------------------------------|
+| =C-M-x=     | =jupyter-eval-defun=            |
+| =M-i=       | =jupyter-inspect-at-point=      |
+| =C-c C-d=   | =jupyter-describe=              |
+| =C-c C-b=   | =jupyter-eval-buffer=           |
+| =C-c C-c=   | =jupyter-eval-line-or-region=   |
+| =C-c C-i=   | =jupyter-repl-interrupt-kernel= |
+| =C-c C-r=   | =jupyter-repl-restart-kernel=   |
+| =C-c C-s=   | =jupyter-repl-scratch-buffer=   |
+| =C-c C-o=   | =jupyter-eval-remove-overlays=  |
+| =C-c M-:=   | =jupyter-eval-string=           |
 
 **** Integration with =emacsclient=
 

jupyter-client.el

@@ -946,24 +946,32 @@ client local variable.
 
 Methods that extend this generic function should
 `cl-call-next-method' as a last step."
-  (cl-check-type jupyter-current-client jupyter-kernel-client
-                 "Need a client to read an expression")
   (let* ((client jupyter-current-client)
          (jupyter--read-expression-history
           (jupyter-get client 'jupyter-eval-expression-history)))
-    (minibuffer-with-setup-hook
-        (lambda ()
-          (setq jupyter-current-client client)
-          (add-hook 'completion-at-point-functions
-                    'jupyter-completion-at-point nil t)
-          (add-hook 'minibuffer-exit-hook
-                    'jupyter--teardown-minibuffer nil t))
-      (prog1 (read-from-minibuffer
-              (format "Eval (%s): " (jupyter-kernel-language client))
-              nil read-expression-map
-              nil 'jupyter--read-expression-history)
-        (jupyter-set client 'jupyter-eval-expression-history
-                     jupyter--read-expression-history)))))
+    (prog1
+        (jupyter--read-with-completion
+         client "Eval (%s): " jupyter--read-expression-history)
+      (jupyter-set client 'jupyter-eval-expression-history
+                   jupyter--read-expression-history))))
+
+(defun jupyter--read-with-completion (client prompt &optional history)
+  "Read an expression using CLIENT for completion.
+The expression is read from the minibuffer with PROMPT and expression
+history HISTORY."
+  (cl-check-type client jupyter-kernel-client
+                 "Need a client to read an expression")
+  (minibuffer-with-setup-hook
+      (lambda ()
+        (setq jupyter-current-client client)
+        (add-hook 'completion-at-point-functions
+                  'jupyter-completion-at-point nil t)
+        (add-hook 'minibuffer-exit-hook
+                  'jupyter--teardown-minibuffer nil t))
+    (read-from-minibuffer
+     (format prompt (jupyter-kernel-language client))
+     nil read-expression-map
+     nil history)))
 
 (defun jupyter-eval (code &optional mime)
   "Send an execute request for CODE, wait for the execute result.
@@ -1419,6 +1427,16 @@ BUFFER and DETAIL have the same meaning as in `jupyter-inspect'."
       (jupyter-code-context 'inspect)
     (jupyter-inspect code pos buffer detail)))
 
+(cl-defgeneric jupyter-describe (code &optional buffer detail)
+  "Inspect CODE provided interactively.
+Call `jupter-inspect' for CODE which can be interactively supplied by user.
+
+BUFFER and DETAIL have the same meaning a in `jupyter-inspect'."
+  (interactive (list (jupyter--read-with-completion
+                      jupyter-current-client "Describe (%s): ")
+                     nil 0))
+  (jupyter-inspect code nil buffer detail))
+
 (cl-defgeneric jupyter-inspect (code &optional pos buffer detail)
   "Inspect CODE.
 Send an `:inspect-request' with the `jupyter-current-client' and

jupyter-repl.el

@@ -44,6 +44,7 @@
 ;;     C-c C-c `jupyter-eval-line-or-region'
 ;;     C-c C-l `jupyter-eval-file'
 ;;     M-i `jupyter-inspect-at-point'
+;;     C-c C-d `jupyter-describe'
 ;;     C-c C-r `jupyter-repl-restart-kernel'
 ;;     C-c C-i `jupyter-repl-interrupt-kernel'
 ;;     C-c C-z `jupyter-repl-pop-to-buffer'
@@ -1947,6 +1948,7 @@ the updated state."
     (define-key map (kbd "C-c C-l") #'jupyter-load-file)
     (define-key map (kbd "C-c M-:") #'jupyter-eval-string-command)
     (define-key map (kbd "M-i") #'jupyter-inspect-at-point)
+    (define-key map (kbd "C-c C-d") #'jupyter-describe)
     (define-key map (kbd "C-c C-r") #'jupyter-repl-restart-kernel)
     (define-key map (kbd "C-c C-i") #'jupyter-repl-interrupt-kernel)
     (define-key map (kbd "C-c C-z") #'jupyter-repl-pop-to-buffer)