Elpy: Command to edit current docstring in rst-mode

[bersace]

Hi,

When docstrings are in rst, this is a must have to have rst-mode in docstring.

I reworked https://github.com/mangalam-research/software-standards/blob/master/emacs/mmm-rst-python.el . I'm using it for a month. Here is the code.

(defun rst-python-statement-is-docstring (begin)
  "Return true if beginning of statiment is :begin"
  (save-excursion
    (save-match-data
      (python-nav-beginning-of-statement)
      (looking-at-p begin))))

(defun rst-python-front-verify ()
  (rst-python-statement-is-docstring (match-string 0)))

(require 'mmm-mode)

(add-to-list 'mmm-save-local-variables 'adaptive-fill-regexp)
(add-to-list 'mmm-save-local-variables 'fill-paragraph-function)

(mmm-add-classes
 '((rst-python-docstrings
    :submode rst-mode
    :face mmm-comment-submode-face
    :front "u?\\(\"\"\"\\|\'\'\'\\)"
    :front-verify rst-python-front-verify
    :back "~1"
    :end-not-begin t
    :save-matches 1
    ;; :front rst-python-docstrings-find-front
    ;; :back rst-python-docstrings-find-back
    :insert ((?d embdocstring nil @ "u\"\"\"" @ _ @ "\"\"\"" @))
    :delimiter-mode nil)))

(mmm-add-mode-ext-class 'python-mode nil 'rst-python-docstrings)

What about including this feature in elpy ?

Regards,
Étienne

[bersace]

The verify function prevent rst-mode in assignment.

var = """is NOT in rst-mode"""
function("""is NOT in rst-mode""")

u""" IS rst-mode"""

[jorgenschaefer]

Thank you for the contribution. I'm afraid I am not willing to have Elpy depend on mmm-mode – but this might be useful for others.

(In general, mixing major modes in Emacs is very tricky, and all approaches so far have been pretty bad hacks, so I'm not sure this can be solved at all.)

[bersace]

I understand. Do you have an alternative for this feature ?

[jorgenschaefer]

As I said, mixing major modes – that is, having multiple major modes active in different regions of the main file – is a long-standing problem for Emacs. I am not aware of any one _good_ solution. If mmm-mode works for you, please do keep using it! I just can not in good conscience make Elpy depend on it.

[bersace]

That's fair :) I was thinking at a big python-mode that embed docstring format.

I didn't notice anything wrong yet, except when i misconfigured mmm.

[birkenfeld]

I have used (or tried to use) mmm in the past (for HTML template code), and it worked okay, but introduced a lot of "lag" into the editing, especially when moving through code with lots of mode switches fast. Maybe this is fixed with newer mmm or newer Emacs, but I haven't missed it enough to try again.

[jorgenschaefer]

Elpy should provide a command that will copy the contents of the current docstring to a new buffer, which is in rst-mode, and allow the user to replace the original docstring with C-c C-c.

[bersace]

Nice :)

[cpitclaudel]

Indeed, this would be a nice idea — in the style of what org-mode does with C-c '

[xuhdev]

And we should highlight the docstring as rst as well.

[fleimgruber]

I did a bit of research on existing libraries for this and found https://github.com/Fanael/edit-indirect. It is e.g. used in https://github.com/purcell/edit-indirect-region-latex.

I put together a quick sketch on how it could be applied to this issue, see https://gist.github.com/fleimgruber/cd2386d8326fad3e0e2b99ebc2f05739.

Given

def example(game):
    """
    heading
    =======

    A list
    * one
    * two

    Some directive
    .. math::
       a^2 + b^2 = c^2
    """
    pass

with point inside the docstring and pressing C-c e (see gist above) an rst-mode buffer should pop up. A C-c ' should jump back to the docstring reflecting the changes, if any.

This is just a proof-of-concept and would need some more thought (especially on edge cases and the crude regexp search and replace in there). What do you think? Does it look promising?