Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
292 lines (248 sloc) 8.74 KB
;;; wikidoc.el --- use elisp doc strings to make other documentation
;; Copyright (C) 2010, 2011, 2012 Nic Ferrier
;; Author: Nic Ferrier <>
;; Maintainer: Nic Ferrier <>
;; Created: 5th October 2010
;; Package-requires: ((s.el "1.9.0"))
;; Version: 0.9
;; Keywords: lisp
;; This file is NOT part of GNU Emacs.
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <>.
;;; Commentary:
;; This is for making documentation from Elisp doc strings. It is
;; intended as an alternative to using info.
;; Right now, the only output format is creole-wiki. But that could
;; change.
;;; Source code
;;; Style note
;; This codes uses the emacs style of:
;; wikidoc---private-function
;; for private functions.
;;; Examples
;; This is the main paragraph converter:
;; (wikidoc--convert "this is a function.
;; this is an example
;; this should 'not' be changed to a link
;; This is the main text. It can include references to other 'functions'.
;; When there are 'two' references 'on the same line' it should
;; still work.")
;;; Code:
(require 's)
(eval-when-compile (require 'cl))
(defun wikidoc-grab-list (prefix &optional no-private)
"Grab a list or functions matching PREFIX possibly with NO-PRIVATE"
(let ((prefix-sym (symbol-name prefix))
(res '()))
(lambda (atom)
(let ((sn (symbol-name atom)))
(and (fboundp atom)
(if (string-prefix-p prefix-sym sn)
(if no-private
(if (not (string-match "[^-]+--.*" sn))
(setq res (cons atom res)))
(setq res (cons atom res)))))))
(defconst wikidoc--convert-line-creole-name-reference "[[%s]]")
(defconst wikidoc--convert-line-creole-arg-reference "//%s//")
(defconst wikidoc--convert-line-name-reference
(defconst wikidoc--convert-line-arg-reference
(defun wikidoc--convert-line (line &optional arguments-to-mangle)
"Converts a single LINE of function documentation.
This deals with things like quoted LISP forms which can be turned
into links.
ARGUMENTS-TO-MANGLE can be a list of arguments which are to be
detected and replaced like:
ARGUMENT -> //argument//
The list should be of symbols, not strings."
(let* ((case-fold-search nil)
(when arguments-to-mangle
(loop for arg in
;; CL style arguments are a list of lists
((and (listp arguments-to-mangle)
(listp (car arguments-to-mangle)))
(car arguments-to-mangle))
;; Normal function args are just a list
((listp arg)
(upcase (symbol-name (car arg))))
((symbolp arg)
(upcase (symbol-name arg)))))))))
(while (string-match ".*\\(`[^']+'\\).*" line)
(setq line
(let ((name (match-string 1 line)))
(string-match "`\\([^']+\\)'" name)
(match-string 1 name))))
nil nil line 1)))
(if arglstre
(lambda (matched)
(downcase matched)))
line t nil)
(defun wikidoc--convert (str &optional arguments-to-mangle)
"Convert function documentation type doc STR to creole.
ARGUMENTS-TO-MANGLE can be a list of arguments which are to be
detected and replaced like:
ARGUMENT -> //argument//
The list should be of symbols, not strings."
(let (in-pre)
(lambda (line)
((string-match "^ " line)
(if in-pre
(setq in-pre 't)
(wikidoc--convert-line line arguments-to-mangle)))))
((and in-pre (not (string-match "^ " line)))
(setq in-pre nil)
(concat "}}}\n" (wikidoc--convert-line line arguments-to-mangle)))
(wikidoc--convert-line line arguments-to-mangle))))
(split-string str "\n")
;; end any pre that we started
(if in-pre "\n}}}\n"))))
(defconst wikidoc--convert-fn-creole-template
"=== ${name} ${args} ===\n\n${description}\n\n\n")
(defconst wikidoc--convert-fn-template wikidoc--convert-fn-creole-template
"By default this is `wikidoc--convert-fn-creole-template'.
The `s-format' keys used are:
NAME - the name of the function
ARGS - the arg list of the function
DESCRIPTION - the function doc body
Each can be put in the template in whatever way you like")
(defun wikidoc--convert-args (args)
(lambda (arg)
(equal '&optional arg)
(equal '&key arg)
(equal '&rest arg))
(format "%s" arg))
((listp arg)
(add-to-list 'arglist (car arg))
(format "%s (%S)"
(car arg)
(cadr arg)))
(add-to-list 'arglist arg)
(format "%s" arg))))
(if (and (listp args)
(listp (car args)))
(car args)
" "))
(defun wikidoc--convert-fn (fn)
"Converter function for documentation of FN to WikiCreole.
The documentation is written, in WikiCreole form, into the
current buffer."
(let* (arglist
(documentation fn) nil)
(cons "()" (documentation fn))))
(car fundoc-list))))
(help-function-arglist fn t)))
(docbody (cdr fundoc-list))
`(("name" . ,(symbol-name fn)) ;; the func name
("args" . ,(wikidoc--convert-args args)) ;; the args
("description" .
,(when docbody
(wikidoc--convert docbody arglist)))))))
(when (and docbody fmted)
(insert fmted))))
(defun wikidoc-insert (elisp-prefix buffer)
"Make creole doc for functions beginning with ELISP-PREFIX in BUFFER.
When called interactively with a PREFIX argument this function
will use the current buffer for BUFFER.
Otherwise the BUFFER will be created named like:
If Transient Mark mode is set in the specified buffer the active
region is killed before the new wiki text is inserted.
(let ((elisp-prefix
(completing-read "elisp prefix: "
obarray nil nil nil nil)))
(list (intern elisp-prefix)
(if current-prefix-arg
(let* ((lst (sort
(wikidoc-grab-list elisp-prefix 't)
(if (not (bufferp buffer))
(setq buffer (get-buffer-create (format "*wikidoc-%s*" elisp-prefix)))
(with-current-buffer buffer
(mapc 'wikidoc--convert-fn lst))
(switch-to-buffer buffer))
(with-current-buffer buffer
(if (use-region-p)
(delete-region (region-beginning) (region-end)))
(mapc 'wikidoc--convert-fn lst))))))
(defun wikidoc-rst-example ()
"This is just an example function. Check the source."
;; rebind the template variables to make rst come out
(let ((wikidoc--convert-fn-template
"\n\n.. el:function:: `${name}' ${args}\n\t${description}\n")
(wikidoc--convert-line-arg-reference "``%s''"))
(wikidoc-insert 'gh-issues- (current-buffer))))
(provide 'wikidoc)
;;; wikidoc.el ends here