bug#22665: 24.5; PROPOSAL: add full docs for symbol at point for Python mode along with existing one-line.

[Oleksandr Gavenko]

`python-eldoc-setup-code' from lisp/progmodes/python.el have:

        else:
            doc = doc.splitlines()[0]

This line from changes:

  commit 15cc40b8199735e600ddf718b936917ff4d79db0
  Author: Fabián Ezequiel Gallina <fgallina@cuca>
  Date:   2012-05-17 00:03:18 -0300

    Fixed eldoc behavior.
    
          * python-eldoc-setup-code: The code to get help now uses the
            inspect element. When an object doesn't have documentation and
            if it is callable it returns the signature for it. Also when
            an object does contain documentation it only returns the first
            line.

***Also when an object does contain documentation it only returns the first
   line.***

Current code uses `message' to display docs. Previous uses
`with-output-to-temp-buffer'.

In some situation I want to see full docs.

I don't use Python regularly and professionally so one line explanation is not
helpful at all.

Please add alternative function to display full doc in separate buffer (if
text is longer then one line??).

It can be done on same key binding but require command prefix.

================================================================

I made dirty hack to my .emacs based on latest sources, but I like to use
official solution (the difference is that I strip ".splitlines()[0]"):

(defvar my/python-eldoc-setup-code
  "def __PYDOC_get_full_help(obj):
    try:
        import inspect
        try:
            str_type = basestring
        except NameError:
            str_type = str
        if isinstance(obj, str_type):
            obj = eval(obj, globals())
        doc = inspect.getdoc(obj)
        if not doc and callable(obj):
            target = None
            if inspect.isclass(obj) and hasattr(obj, '__init__'):
                target = obj.__init__
                objtype = 'class'
            else:
                target = obj
                objtype = 'def'
            if target:
                args = inspect.formatargspec(
                    *inspect.getargspec(target)
                )
                name = obj.__name__
                doc = '{objtype} {name}{args}'.format(
                    objtype=objtype, name=name, args=args
                )
    except:
        doc = ''
    return doc"
  "Python code to setup documentation retrieval.")

(defvar my/python-eldoc-string-code "__PYDOC_get_full_help('''%s''')"
  "Python code used to get a string with the documentation of an object.")

;; For built-in python.el
(with-eval-after-load 'python
  (add-to-list 'python-shell-setup-codes 'my/python-eldoc-setup-code) ; Used 
inside (python-shell-send-setup-code)
  (defun my/python-eldoc-at-point (&optional symbol)
    (interactive
     (let ((symbol (python-info-current-symbol t))
           (enable-recursive-minibuffers t))
       (list (read-string (if symbol
                              (format "Describe symbol (default %s): " symbol)
                            "Describe symbol: ")
                          nil nil symbol))))
    (let ( (python-eldoc-string-code my/python-eldoc-string-code)
           (python-eldoc-setup-code my/python-eldoc-setup-code) )
      (switch-to-buffer (get-buffer-create "*Python-doc*"))
      (read-only-mode -1)
      (buffer-disable-undo)
      (erase-buffer)
      (insert (python-eldoc--get-doc-at-point symbol))
      (goto-char (point-min))
      (when (re-search-forward "^u?'" (line-end-position) t)
        (replace-match ""))
      (while (re-search-forward "\\\\n" nil t)
        (replace-match "\n"))
      (goto-char (point-max))
      (when (eq ?' (char-before))
        (delete-char -1))
      (read-only-mode 1)
      (goto-char (point-min))))
  (define-key python-mode-map "\C-c\C-d" 'my/python-eldoc-at-point))

-- 
http://defun.work/