branch: elpa/evil
commit be4815e7e779c2cc8898d3ebd17a950d22d04723
Author: Axel Forsman <axels...@gmail.com>
Commit: Axel Forsman <axels...@gmail.com>
Substitute key bindings correctly in manual
The Sphinx Emacs Lisp extension assumed all \[command] key sequence
substitutions in documentation strings are preceded by a \<mapvar>
sequence specifying the keymap, unlike substitute-command-keys which is
used when accessing docstrings within Emacs.
With this commit the actual substitute-command-keys function is used
when building docstringdb.json, instead of the Python reimplementation.
The drawback is that docstringdb.json now contains partial Sphinx
markup.
---
doc/source/_ext/elisp.py | 26 +++-----------
doc/source/conf.py | 5 ---
scripts/evil-extract-docstrings | 79 ++++++++++++++++-------------------------
3 files changed, 35 insertions(+), 75 deletions(-)
diff --git a/doc/source/_ext/elisp.py b/doc/source/_ext/elisp.py
index 924d026b74..a4da67ef98 100644
--- a/doc/source/_ext/elisp.py
+++ b/doc/source/_ext/elisp.py
@@ -18,15 +18,14 @@ with open(path.join(path.dirname(__file__), '..', '..',
'docstringdb.json')) as
DATA = json.load(f)
-re_evilcode = re.compile(r"`(evil-[^']*)'")
-re_code = re.compile(r"`([^:][^ ']*)'")
-re_kwd = re.compile(r"`(:[^']*)'")
+re_evilcode = re.compile(r"‘(evil-[^’]*)’")
+re_code = re.compile(r"‘([^:][^ ’]*)’")
+re_kwd = re.compile(r"‘(:[^’]*)’")
re_item = re.compile(r"([^\n])\n- ")
-re_sexp = re.compile(r"\([A-Z \-\.'`\[\]]+\)|[A-Z\-]+")
+re_sexp = re.compile(r"\([A-Z \-\.‘’\[\]]+\)|[A-Z\-]+")
re_capitals = re.compile(r"[A-Z\-]+")
re_nonspace = re.compile(r"[^ ]")
re_signature = re.compile(r'\(fn (.*)\)')
-re_keymap_or_kbd = re.compile(r"\\[\[<]([^\]>]*)[\]>]")
emphasis = [
'thing-at-point',
@@ -52,7 +51,7 @@ def process_docstring(docstring, capitals=None):
in_block = False
for line in lines:
try:
- indented = next(re_nonspace.finditer(line)).start(0) > 3
+ indented = next(re_nonspace.finditer(line)).start(0) >= 4
except StopIteration:
indented = None
if indented is True and not in_block:
@@ -73,21 +72,6 @@ def process_docstring(docstring, capitals=None):
# Substitute `:alpha' with ``alpha``
docstring = re_kwd.sub(r'``\1``', docstring)
- # Translate key bindings
- keymap = None
- def substitute_binding(match):
- nonlocal keymap
- if match.group(0)[1] == '<':
- keymap = match.group(1)
- return ''
- if keymap is None:
- print(docstring)
- assert False
- return '???'
- key = DATA[keymap]['keymap-inv'][match.group(1)]
- return f':kbd:`{key}`'
- docstring = re_keymap_or_kbd.sub(substitute_binding, docstring)
-
# Add empty line between list items
docstring = re_item.sub(r'\1\n\n- ', docstring)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 8e5f4aeee5..5b1b6f5e88 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -83,8 +83,3 @@ exclude_patterns = []
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
diff --git a/scripts/evil-extract-docstrings b/scripts/evil-extract-docstrings
index ed72109ce1..06afa43e69 100755
--- a/scripts/evil-extract-docstrings
+++ b/scripts/evil-extract-docstrings
@@ -7,53 +7,34 @@
(require 'json)
(require 'help)
-(defun keymap-funcs (map)
- (let (funcs)
- (dolist (elt (cdr map))
- (when (consp elt)
- (cond
- ((and (cdr elt) (symbolp (cdr elt)))
- (push (cdr elt) funcs))
- ((keymapp (cdr elt))
- (setq funcs (append (keymap-funcs (cdr elt)) funcs))))))
- funcs))
+(defun mark-command-keys (string)
+ "Mark key bindings in STRING with the \":kbd:\" Sphinx role."
+ (when string
+ (cl-loop
+ for prev = 0 then pos until (>= prev (length string))
+ for pos = (next-single-property-change prev 'face string (length string))
+ concat
+ (let ((s (substring string prev pos)))
+ (if (eq (get-text-property prev 'face string) 'help-key-binding)
+ (format ":kbd:`%s`" s)
+ s)))))
-(defun keymap-bindings (map)
- (let ((funcs (keymap-funcs map))
- bindings)
- (dolist (func funcs)
- (unless (memq func '(undefined))
- ;; (push (cons func (key-description (where-is-internal func map t)))
bindings)
- ;; (message (format "%s %s" func (key-description (where-is-internal
func map t))))
- (push (cons func (key-description (where-is-internal func map t)))
bindings)))
- bindings))
-
-(with-temp-file (expand-file-name "../doc/docstringdb.json" cur-path)
- (let (vars)
- (mapatoms
- (lambda (sym)
- (when (string-prefix-p "evil-" (symbol-name sym))
- (let ((default (car (get sym 'standard-value))))
- (while (and (consp default) (memq (car default) '(function quote)))
- (setq default (cadr default)))
- (when (eq 'funcall (car-safe default))
- (setq default (eval default)))
- ;; (when (and (boundp sym) (keymapp (symbol-value sym)))
- ;; (message (format "%S" sym)))
- (push `(,sym (default . ,(cond
- ((consp default) (format "%S" default))
- ((symbolp default) (symbol-name default))
- (t default)))
- (local . ,(local-variable-if-set-p sym))
- (default-type . ,(type-of default))
- (var-docstring . ,(documentation-property sym
'variable-documentation 'raw))
- (fn-docstring . ,(ignore-errors (documentation sym
'raw)))
- (arglist . ,(help-function-arglist sym))
- (functionp . ,(functionp sym))
- (macrop . ,(macrop sym))
- (keymap-inv . ,(and (boundp sym)
- (keymapp (symbol-value sym))
- (keymap-bindings (symbol-value
sym)))))
- vars)))))
- (let ((json-encoding-pretty-print t))
- (insert (json-encode vars)))))
+(let (vars)
+ (mapatoms
+ (lambda (sym)
+ (when (string-prefix-p "evil-" (symbol-name sym))
+ (let ((default (eval (car (get sym 'standard-value)))))
+ (push `(,sym (default . ,(cond
+ ((consp default) (format "%S" default))
+ ((symbolp default) (symbol-name default))
+ (t default)))
+ (local . ,(local-variable-if-set-p sym))
+ (default-type . ,(type-of default))
+ (var-docstring . ,(mark-command-keys
(documentation-property sym 'variable-documentation)))
+ (fn-docstring . ,(ignore-errors (mark-command-keys
(documentation sym))))
+ (arglist . ,(help-function-arglist sym))
+ (functionp . ,(functionp sym))
+ (macrop . ,(macrop sym)))
+ vars)))))
+ (with-temp-file (expand-file-name "../doc/docstringdb.json" cur-path)
+ (insert (json-encode vars))))
