182 lines
8.1 KiB
EmacsLisp
182 lines
8.1 KiB
EmacsLisp
;;; python-docstring.el --- Smart Python docstring formatting
|
|
|
|
;; Copyright (c) 2014-2015 The Authors
|
|
;;
|
|
;; Permission is hereby granted, free of charge, to any person obtaining
|
|
;; a copy of this software and associated documentation files (the
|
|
;; "Software"), to deal in the Software without restriction, including
|
|
;; without limitation the rights to use, copy, modify, merge, publish,
|
|
;; distribute, sublicense, and/or sell copies of the Software, and to
|
|
;; permit persons to whom the Software is furnished to do so, subject to
|
|
;; the following conditions:
|
|
;;
|
|
;; The above copyright notice and this permission notice shall be
|
|
;; included in all copies or substantial portions of the Software.
|
|
;;
|
|
;; THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
;; EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
;; MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
;; NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
;; LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
;; OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
;; WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
|
|
;;; Commentary:
|
|
|
|
;; python-docstring-mode.el is a minor mode for intelligently
|
|
;; reformatting (refilling) and highlighting Python docstrings. It
|
|
;; understands both epytext and Sphinx formats (even intermingled!),
|
|
;; so it knows how to reflow them correctly. It will also highlight
|
|
;; markup in your docstrings, including epytext and reStructuredText.
|
|
|
|
;;; Code:
|
|
|
|
(defcustom python-docstring-sentence-end-double-space t
|
|
"If non-nil, use double spaces when formatting text.
|
|
|
|
Operates simililarly to `sentence-end-double-space'. When nil, a
|
|
single space is used."
|
|
:type 'boolean
|
|
:group 'python-docstring)
|
|
|
|
(defvar python-docstring-script
|
|
(concat (if load-file-name
|
|
(file-name-directory load-file-name)
|
|
default-directory)
|
|
"docstring_wrap.py")
|
|
"The location of the docstring_wrap.py script.")
|
|
|
|
;;;###autoload
|
|
(defun python-docstring-fill ()
|
|
"Wrap Python docstrings as epytext or ReStructured Text."
|
|
(interactive)
|
|
(let ((fill-it-anyway nil))
|
|
(catch 'not-a-string
|
|
(let* ((to-forward
|
|
(save-excursion
|
|
(let* ((orig-point (point))
|
|
(syx (syntax-ppss))
|
|
(in-string (if (nth 3 syx) t
|
|
(progn
|
|
(setf fill-it-anyway t)
|
|
(throw 'not-a-string nil))))
|
|
(string-start (+ (goto-char (nth 8 syx))
|
|
3))
|
|
(rawchar (if (eql (char-before (point)) ?r)
|
|
1
|
|
0))
|
|
;; at the beginning of the screen here
|
|
(indent-count (- (- string-start (+ rawchar 3))
|
|
(save-excursion
|
|
(beginning-of-line)
|
|
(point))))
|
|
(string-end
|
|
(- (condition-case () ; for unbalanced quotes
|
|
(progn (forward-sexp)
|
|
(point))
|
|
(error (point-max)))
|
|
3))
|
|
(orig-offset (- orig-point string-start)))
|
|
(let*
|
|
((offset-within
|
|
(progn
|
|
(shell-command-on-region
|
|
string-start string-end
|
|
(format
|
|
(concat "python3 %s --offset %s --indent %s --width %s"
|
|
(unless python-docstring-sentence-end-double-space
|
|
" --single-space"))
|
|
(shell-quote-argument python-docstring-script)
|
|
orig-offset
|
|
indent-count
|
|
fill-column
|
|
)
|
|
:replace t)
|
|
(goto-char string-start)
|
|
(forward-sexp)
|
|
(string-to-number
|
|
(buffer-substring-no-properties string-start orig-point))
|
|
)))
|
|
(delete-region string-start (+ 1 (point)))
|
|
offset-within)))))
|
|
(forward-char to-forward)))
|
|
(if fill-it-anyway
|
|
(call-interactively 'fill-paragraph))))
|
|
|
|
(defvar python-docstring-field-with-arg-re
|
|
"^\\s-*\\([@:]\\)\\(param\\|parameter\\|arg\\|argument\\|type\\|keyword\\|kwarg\\|kwparam\\|raise\\|raises\\|except\\|exception\\|ivar\\|ivariable\\|cvar\\|cvariable\\|var\\|variable\\|type\\|group\\|todo\\|newfield\\)\\s-+\\([a-zA-Z_][a-zA-Z0-9_,. ]*?\\)\\(:\\)")
|
|
|
|
(defvar python-docstring-field-no-arg-re
|
|
"^\\s-*\\([@:]\\)\\(raise\\|raises\\|return\\|returns\\|rtype\\|returntype\\|type\\|sort\\|see\\|seealso\\|note\\|attention\\|bug\\|warning\\|warn\\|version\\|todo\\|deprecated\\|since\\|status\\|change\\|changed\\|permission\\|requires\\|require\\|requirement\\|precondition\\|precond\\|postcondition\\|postcod\\|invariant\\|author\\|organization\\|org\\|copyright\\|(c)\\|license\\|contact\\|summary\\|params\\|param\\)\\(:\\)")
|
|
|
|
(defvar python-docstring-epytext-markup-link "[UL]{\\([^}]*?\\)\\(<.*?>\\|\\)?}")
|
|
(defvar python-docstring-epytext-markup-style-code "C{\\(.*?\\)}")
|
|
(defvar python-docstring-epytext-markup-style-italic "I{\\(.*?\\)}")
|
|
(defvar python-docstring-epytext-markup-style-bold "B{\\(.*?\\)}")
|
|
|
|
;; hack for sphinx
|
|
(defvar python-docstring-sphinx-markup-link "\\(:[^:]+?:\\)\\(`.+?`\\)")
|
|
(defvar python-docstring-sphinx-markup-code "``\\(.+?\\)``")
|
|
|
|
(defvar python-docstring-keywords
|
|
`((,python-docstring-field-with-arg-re 1 font-lock-keyword-face t)
|
|
(,python-docstring-field-with-arg-re 2 font-lock-type-face t)
|
|
(,python-docstring-field-with-arg-re 3 font-lock-variable-name-face t)
|
|
(,python-docstring-field-with-arg-re 4 font-lock-keyword-face t)
|
|
(,python-docstring-field-no-arg-re 1 font-lock-keyword-face t)
|
|
(,python-docstring-field-no-arg-re 2 font-lock-type-face t)
|
|
(,python-docstring-field-no-arg-re 3 font-lock-keyword-face t)
|
|
|
|
;; :foo:`bar`
|
|
(,python-docstring-sphinx-markup-link 1 font-lock-function-name-face t)
|
|
(,python-docstring-sphinx-markup-link 2 font-lock-constant-face t)
|
|
;; ``bar``
|
|
(,python-docstring-sphinx-markup-code 0 font-lock-constant-face t)
|
|
;; inline markup - 1
|
|
(,python-docstring-sphinx-markup-code 1 '(bold italic) t)
|
|
|
|
;; L/U - 1
|
|
(,python-docstring-epytext-markup-link 0 font-lock-constant-face t)
|
|
;; Inline Markup - 1
|
|
(,python-docstring-epytext-markup-link 1 font-lock-function-name-face t)
|
|
;; Link - 2
|
|
(,python-docstring-epytext-markup-link 2 font-lock-keyword-face t)
|
|
|
|
;; C/I/B - 0
|
|
(,python-docstring-epytext-markup-style-code 0 font-lock-constant-face t)
|
|
;; inline markup - 1
|
|
(,python-docstring-epytext-markup-style-code 1 '(bold italic) t)
|
|
;; C/I/B - 0
|
|
(,python-docstring-epytext-markup-style-bold 0 font-lock-constant-face t)
|
|
;; inline markup - 1
|
|
(,python-docstring-epytext-markup-style-bold 1 (quote bold) t)
|
|
;; C/I/B - 0
|
|
(,python-docstring-epytext-markup-style-italic 0 font-lock-constant-face t)
|
|
;; inline markup - 1
|
|
(,python-docstring-epytext-markup-style-italic 1 (quote italic) t)))
|
|
|
|
;;;###autoload
|
|
(define-minor-mode python-docstring-mode
|
|
"Toggle python-docstring-mode.
|
|
With no argument, this command toggles the mode.
|
|
Non-null prefix argument turns on the mode.
|
|
Null prefix argument turns off the mode."
|
|
;; The initial value.
|
|
nil
|
|
;; The indicator for the mode line.
|
|
" DS"
|
|
;; The minor mode bindings.
|
|
`(([(meta q)] . python-docstring-fill))
|
|
;; &rest BODY
|
|
(if python-docstring-mode
|
|
(font-lock-add-keywords nil python-docstring-keywords)
|
|
(font-lock-remove-keywords nil python-docstring-keywords)))
|
|
|
|
;;;###autoload
|
|
(defun python-docstring-install ()
|
|
"Add python-docstring-mode as a hook to python.mode."
|
|
(add-hook 'python-mode-hook (lambda () (python-docstring-mode t))))
|
|
|
|
(provide 'python-docstring)
|
|
|
|
;;; python-docstring.el ends here
|