Skip to content
Newer
Older
100644 292 lines (248 sloc) 8.74 KB
b8d5c99 initial checkin
nferrier authored
1 ;;; wikidoc.el --- use elisp doc strings to make other documentation
2
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
3 ;; Copyright (C) 2010, 2011, 2012 Nic Ferrier
b8d5c99 initial checkin
nferrier authored
4
5 ;; Author: Nic Ferrier <nic@ferrier.me.uk>
6 ;; Maintainer: Nic Ferrier <nic@ferrier.me.uk>
7 ;; Created: 5th October 2010
ce82fd2 @nicferrier require s for new stuff
authored
8 ;; Package-requires: ((s.el "1.9.0"))
8a85253 @nicferrier bump the version
authored
9 ;; Version: 0.9
b8d5c99 initial checkin
nferrier authored
10 ;; Keywords: lisp
11
12 ;; This file is NOT part of GNU Emacs.
13
14 ;; This program is free software; you can redistribute it and/or modify
15 ;; it under the terms of the GNU General Public License as published by
16 ;; the Free Software Foundation, either version 3 of the License, or
17 ;; (at your option) any later version.
18
19 ;; This program is distributed in the hope that it will be useful,
20 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
21 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 ;; GNU General Public License for more details.
23
24 ;; You should have received a copy of the GNU General Public License
25 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
26
27 ;;; Commentary:
28 ;;
29 ;; This is for making documentation from Elisp doc strings. It is
30 ;; intended as an alternative to using info.
31 ;;
32 ;; Right now, the only output format is creole-wiki. But that could
33 ;; change.
34
35 ;;; Source code
36 ;;
92d9fb4 @nicferrier reference to wikidoc github
authored
37 ;; https://github.com/nicferrier/elwikidoc
b8d5c99 initial checkin
nferrier authored
38
39 ;;; Style note
40 ;;
41 ;; This codes uses the emacs style of:
42 ;;
385bf5a @nicferrier fixup whitespace properly
authored
43 ;; wikidoc---private-function
b8d5c99 initial checkin
nferrier authored
44 ;;
45 ;; for private functions.
46 ;;
47 ;;; Examples
385bf5a @nicferrier fixup whitespace properly
authored
48 ;;
b8d5c99 initial checkin
nferrier authored
49 ;; This is the main paragraph converter:
50 ;;
51 ;; (wikidoc--convert "this is a function.
52 ;; this is an example
53 ;; this should 'not' be changed to a link
54 ;; This is the main text. It can include references to other 'functions'.
55 ;; When there are 'two' references 'on the same line' it should
56 ;; still work.")
57
55f43ca @nicferrier merge back changes for elpa
authored
58 ;;; Code:
59
ce82fd2 @nicferrier require s for new stuff
authored
60 (require 's)
e6a51bd @nicferrier fix convert-line regex case problem
authored
61 (eval-when-compile (require 'cl))
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
62
b8d5c99 initial checkin
nferrier authored
63 ;;;###autoload
64 (defun wikidoc-grab-list (prefix &optional no-private)
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
65 "Grab a list or functions matching PREFIX possibly with NO-PRIVATE"
b8d5c99 initial checkin
nferrier authored
66 (let ((prefix-sym (symbol-name prefix))
67 (res '()))
385bf5a @nicferrier fixup whitespace properly
authored
68 (mapatoms
b8d5c99 initial checkin
nferrier authored
69 (lambda (atom)
70 (let ((sn (symbol-name atom)))
71 (and (fboundp atom)
72 (if (string-prefix-p prefix-sym sn)
73 (if no-private
74 (if (not (string-match "[^-]+--.*" sn))
75 (setq res (cons atom res)))
76 (setq res (cons atom res)))))))
77 obarray)
78 res))
79
b310540 @nicferrier begin to abstract wikidoc for other text styles.
authored
80 (defconst wikidoc--convert-line-creole-name-reference "[[%s]]")
81 (defconst wikidoc--convert-line-creole-arg-reference "//%s//")
82
83 (defconst wikidoc--convert-line-name-reference
84 wikidoc--convert-line-creole-name-reference)
85
86 (defconst wikidoc--convert-line-arg-reference
87 wikidoc--convert-line-creole-arg-reference)
88
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
89 (defun wikidoc--convert-line (line &optional arguments-to-mangle)
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
90 "Converts a single LINE of function documentation.
b8d5c99 initial checkin
nferrier authored
91
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
92 This deals with things like quoted LISP forms which can be turned
93 into links.
94
95 ARGUMENTS-TO-MANGLE can be a list of arguments which are to be
96 detected and replaced like:
97
98 ARGUMENT -> //argument//
99
100 The list should be of symbols, not strings."
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
101 (let* ((case-fold-search nil)
102 (arglstre
103 (when arguments-to-mangle
104 (regexp-opt
105 (loop for arg in
106 (cond
107 ;; CL style arguments are a list of lists
108 ((and (listp arguments-to-mangle)
109 (listp (car arguments-to-mangle)))
110 (car arguments-to-mangle))
111 ;; Normal function args are just a list
112 (t
113 arguments-to-mangle))
114 collect
115 (cond
116 ((listp arg)
117 (upcase (symbol-name (car arg))))
118 ((symbolp arg)
119 (upcase (symbol-name arg)))))))))
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
120 (save-match-data
e6a51bd @nicferrier fix convert-line regex case problem
authored
121 (while (string-match ".*\\(`[^']+'\\).*" line)
122 (setq line
123 (replace-match
b310540 @nicferrier begin to abstract wikidoc for other text styles.
authored
124 (format
125 wikidoc--convert-line-name-reference
126 (let ((name (match-string 1 line)))
127 (save-match-data
128 (string-match "`\\([^']+\\)'" name)
129 (match-string 1 name))))
e6a51bd @nicferrier fix convert-line regex case problem
authored
130 nil nil line 1)))
385bf5a @nicferrier fixup whitespace properly
authored
131 (if arglstre
132 (replace-regexp-in-string
133 arglstre
b310540 @nicferrier begin to abstract wikidoc for other text styles.
authored
134 (lambda (matched)
135 (format
136 wikidoc--convert-line-arg-reference
137 (downcase matched)))
e6a51bd @nicferrier fix convert-line regex case problem
authored
138 line t nil)
139 line))))
385bf5a @nicferrier fixup whitespace properly
authored
140
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
141 (defun wikidoc--convert (str &optional arguments-to-mangle)
142 "Convert function documentation type doc STR to creole.
143
144 ARGUMENTS-TO-MANGLE can be a list of arguments which are to be
145 detected and replaced like:
146
147 ARGUMENT -> //argument//
148
149 The list should be of symbols, not strings."
754eb7c @nicferrier update the version
authored
150 (let (in-pre)
385bf5a @nicferrier fixup whitespace properly
authored
151 (concat
754eb7c @nicferrier update the version
authored
152 (mapconcat
153 (lambda (line)
154 (cond
155 ((string-match "^ " line)
156 (if in-pre
157 line
385bf5a @nicferrier fixup whitespace properly
authored
158 (progn
754eb7c @nicferrier update the version
authored
159 (setq in-pre 't)
385bf5a @nicferrier fixup whitespace properly
authored
160 (concat
161 "{{{\n"
162 (wikidoc--convert-line line arguments-to-mangle)))))
754eb7c @nicferrier update the version
authored
163 ((and in-pre (not (string-match "^ " line)))
385bf5a @nicferrier fixup whitespace properly
authored
164 (setq in-pre nil)
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
165 (concat "}}}\n" (wikidoc--convert-line line arguments-to-mangle)))
385bf5a @nicferrier fixup whitespace properly
authored
166 ('t
1c7a3e7 @nicferrier added translation of function args to the list of stuff done.
authored
167 (wikidoc--convert-line line arguments-to-mangle))))
754eb7c @nicferrier update the version
authored
168 (split-string str "\n")
169 "\n")
170 ;; end any pre that we started
171 (if in-pre "\n}}}\n"))))
b8d5c99 initial checkin
nferrier authored
172
b310540 @nicferrier begin to abstract wikidoc for other text styles.
authored
173 (defconst wikidoc--convert-fn-creole-template
174 "=== ${name} ${args} ===\n\n${description}\n\n\n")
175
176 (defconst wikidoc--convert-fn-template wikidoc--convert-fn-creole-template
177 "By default this is `wikidoc--convert-fn-creole-template'.
178
179 The `s-format' keys used are:
180
181 NAME - the name of the function
182 ARGS - the arg list of the function
183 DESCRIPTION - the function doc body
184
185 Each can be put in the template in whatever way you like")
186
187 (defun wikidoc--convert-args (args)
188 (mapconcat
189 (lambda (arg)
190 (cond
191 ((or
192 (equal '&optional arg)
193 (equal '&key arg)
194 (equal '&rest arg))
195 (format "%s" arg))
196 ((listp arg)
197 (add-to-list 'arglist (car arg))
198 (format "%s (%S)"
199 (car arg)
200 (cadr arg)))
201 ('t
202 (add-to-list 'arglist arg)
203 (format "%s" arg))))
204 (if (and (listp args)
205 (listp (car args)))
206 (car args)
207 args)
208 " "))
209
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
210 (defun wikidoc--convert-fn (fn)
742ceaa @nicferrier fixes for the buffer specificity.
authored
211 "Converter function for documentation of FN to WikiCreole.
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
212
742ceaa @nicferrier fixes for the buffer specificity.
authored
213 The documentation is written, in WikiCreole form, into the
214 current buffer."
215 (let* (arglist
216 (fundoc-list
217 (or
218 (help-split-fundoc
219 (documentation fn) nil)
220 (cons "()" (documentation fn))))
221 (args
222 (or
223 (cdar
224 (read-from-string
225 (downcase
226 (car fundoc-list))))
227 (help-function-arglist fn t)))
228 (docbody (cdr fundoc-list))
229 (fmted
b310540 @nicferrier begin to abstract wikidoc for other text styles.
authored
230 (s-format
231 wikidoc--convert-fn-template
232 'aget
233 `(("name" . ,(symbol-name fn)) ;; the func name
234 ("args" . ,(wikidoc--convert-args args)) ;; the args
235 ("description" .
236 ,(when docbody
237 (wikidoc--convert docbody arglist)))))))
742ceaa @nicferrier fixes for the buffer specificity.
authored
238 (when (and docbody fmted)
239 (insert fmted))))
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
240
b8d5c99 initial checkin
nferrier authored
241 ;;;###autoload
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
242 (defun wikidoc-insert (elisp-prefix buffer)
243 "Make creole doc for functions beginning with ELISP-PREFIX in BUFFER.
244
245 When called interactively with a PREFIX argument this function
385bf5a @nicferrier fixup whitespace properly
authored
246 will use the current buffer for BUFFER.
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
247
248 Otherwise the BUFFER will be created named like:
249
250 *wikidoc-ELISP-PREFIX*
d0e8202 document the region-kill for wikidoc-insert.
nferrier authored
251
252 If Transient Mark mode is set in the specified buffer the active
253 region is killed before the new wiki text is inserted.
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
254 "
385bf5a @nicferrier fixup whitespace properly
authored
255 (interactive
256 (let ((elisp-prefix
257 (completing-read "elisp prefix: "
258 obarray nil nil nil nil)))
259 (list (intern elisp-prefix)
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
260 (if current-prefix-arg
261 (current-buffer)
262 nil))))
385bf5a @nicferrier fixup whitespace properly
authored
263 (let* ((lst (sort
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
264 (wikidoc-grab-list elisp-prefix 't)
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
265 'string-lessp)))
b8d5c99 initial checkin
nferrier authored
266 (if (not (bufferp buffer))
267 (progn
7e208c1 fix doc and make wikidoc-insert insert into current buffer with prefix.
nferrier authored
268 (setq buffer (get-buffer-create (format "*wikidoc-%s*" elisp-prefix)))
742ceaa @nicferrier fixes for the buffer specificity.
authored
269 (with-current-buffer buffer
270 (mapc 'wikidoc--convert-fn lst))
b8d5c99 initial checkin
nferrier authored
271 (switch-to-buffer buffer))
1a76967 make wikidoc-insert delete any region if we're using a specified buffer.
nferrier authored
272 (progn
742ceaa @nicferrier fixes for the buffer specificity.
authored
273 (with-current-buffer buffer
274 (if (use-region-p)
275 (delete-region (region-beginning) (region-end)))
276 (mapc 'wikidoc--convert-fn lst))))))
b8d5c99 initial checkin
nferrier authored
277
b310540 @nicferrier begin to abstract wikidoc for other text styles.
authored
278
279 (defun wikidoc-rst-example ()
280 "This is just an example function. Check the source."
281
282 ;; rebind the template variables to make rst come out
283
284 (let ((wikidoc--convert-fn-template
285 "\n\n.. el:function:: `${name}' ${args}\n\t${description}\n")
286 (wikidoc--convert-line-arg-reference "``%s''"))
287 (wikidoc-insert 'gh-issues- (current-buffer))))
288
0687027 @tarsius provide feature
tarsius authored
289 (provide 'wikidoc)
f76b2f5 @nicferrier lots of small changes that cope with CL style functions, defun* etc...
authored
290
55f43ca @nicferrier merge back changes for elpa
authored
291 ;;; wikidoc.el ends here
Something went wrong with that request. Please try again.