Refrain from evaluating buffer
Evaluating the buffer requires that all required libraries and functions are present at the moment the documentation is generated. Because documentation generation may happen in an Emacs without X11 support or without all the libraries installed, this is not an optimal solution.
This commit is contained in:
parent
081ca68d03
commit
3312852701
1 changed files with 41 additions and 7 deletions
48
edocs.el
48
edocs.el
|
@ -84,6 +84,37 @@ and are not meant to be used outside the module. The default is
|
||||||
"defvar" "Variable"))
|
"defvar" "Variable"))
|
||||||
"Type -> name map for symbol types.")
|
"Type -> name map for symbol types.")
|
||||||
|
|
||||||
|
(defun edocs--get-doc (expr)
|
||||||
|
"Get a docstring from EXPR."
|
||||||
|
(cl-case (car expr)
|
||||||
|
((defun defcustom defgroup defface)
|
||||||
|
(let ((doc (nth 3 expr)))
|
||||||
|
(when (stringp doc) doc)))
|
||||||
|
((defvar defconst defgeneric)
|
||||||
|
(let ((doc (car (last expr))))
|
||||||
|
(when (and (= (length expr) 4)
|
||||||
|
(stringp doc))
|
||||||
|
doc)))
|
||||||
|
(define-minor-mode
|
||||||
|
(let ((doc (nth 2 expr)))
|
||||||
|
(when (stringp doc) doc)))
|
||||||
|
(defclass
|
||||||
|
(let ((doc (or (plist-git expr :documentation)
|
||||||
|
(nth 4 expr))))
|
||||||
|
(when (stringp doc) doc)))
|
||||||
|
(defmethod
|
||||||
|
(let ((doc1 (nth 3 expr))
|
||||||
|
(doc2 (nth 4 expr)))
|
||||||
|
(or (and (stringp doc1) doc1)
|
||||||
|
(and (stringp doc2) doc2))))))
|
||||||
|
|
||||||
|
(defun edocs--get-arg-list (expr)
|
||||||
|
"Get argument list from EXPR if possible."
|
||||||
|
(when (eql (car expr) 'defun)
|
||||||
|
(format "%s" (or (nth 2 expr) "()"))))
|
||||||
|
|
||||||
|
(cl-defstruct edocs-symbol name type doc args)
|
||||||
|
|
||||||
(defun edocs--list-symbols ()
|
(defun edocs--list-symbols ()
|
||||||
"Get a list of all symbols in the buffer.
|
"Get a list of all symbols in the buffer.
|
||||||
|
|
||||||
|
@ -103,7 +134,10 @@ etc."
|
||||||
(let ((type (symbol-name (car expr)))
|
(let ((type (symbol-name (car expr)))
|
||||||
(name (symbol-name (cadr expr))))
|
(name (symbol-name (cadr expr))))
|
||||||
(unless (string-match edocs-private-regexp name)
|
(unless (string-match edocs-private-regexp name)
|
||||||
(push (cons type name) ls))))))
|
(push (make-edocs-symbol
|
||||||
|
:name name :type type
|
||||||
|
:doc (edocs--get-doc expr)
|
||||||
|
:args (edocs--get-arg-list expr)) ls))))))
|
||||||
(end-of-file nil))
|
(end-of-file nil))
|
||||||
(reverse ls))))
|
(reverse ls))))
|
||||||
|
|
||||||
|
@ -238,9 +272,10 @@ See the docstring for `edocs--module-name' for more information."
|
||||||
|
|
||||||
KNOWN-SYMBOLS is used for referencing symbols found in other
|
KNOWN-SYMBOLS is used for referencing symbols found in other
|
||||||
parts of the module."
|
parts of the module."
|
||||||
(let* ((type (car symbol))
|
(let ((type (edocs-symbol-type symbol))
|
||||||
(name (cdr symbol))
|
(name (edocs-symbol-name symbol))
|
||||||
(docs (edocs--get-docs type name)))
|
(docs (edocs-symbol-doc symbol))
|
||||||
|
(args (edocs-symbol-args symbol)))
|
||||||
(mapc (lambda (doc)
|
(mapc (lambda (doc)
|
||||||
(edocs--with-tag "div" nil
|
(edocs--with-tag "div" nil
|
||||||
(insert "– ")
|
(insert "– ")
|
||||||
|
@ -251,7 +286,7 @@ parts of the module."
|
||||||
(edocs--with-tag "a" `(("name" . ,name)
|
(edocs--with-tag "a" `(("name" . ,name)
|
||||||
("href" . ,(concat "#" name)))
|
("href" . ,(concat "#" name)))
|
||||||
(insert name)))
|
(insert name)))
|
||||||
(insert " " (if (consp doc) (car doc) ""))
|
(insert " " (or args ""))
|
||||||
(edocs--with-tag "blockquote" '(("class" . "docstring"))
|
(edocs--with-tag "blockquote" '(("class" . "docstring"))
|
||||||
(insert (or (edocs--format-doc doc known-symbols)
|
(insert (or (edocs--format-doc doc known-symbols)
|
||||||
"Not documented.")))))
|
"Not documented.")))))
|
||||||
|
@ -270,7 +305,7 @@ into a buffer called `*edocs*' and switches to that buffer."
|
||||||
(binfo (package-buffer-info))
|
(binfo (package-buffer-info))
|
||||||
(commentary (lm-commentary))
|
(commentary (lm-commentary))
|
||||||
(symbol-specs (edocs--list-symbols))
|
(symbol-specs (edocs--list-symbols))
|
||||||
(symbols (mapcar #'cdr symbol-specs)))
|
(symbols (mapcar #'edocs-symbol-type symbol-specs)))
|
||||||
(with-current-buffer buffer
|
(with-current-buffer buffer
|
||||||
(unless edocs-generate-only-body (edocs--insert-header))
|
(unless edocs-generate-only-body (edocs--insert-header))
|
||||||
(edocs--with-tag "div" '(("class" . "container"))
|
(edocs--with-tag "div" '(("class" . "container"))
|
||||||
|
@ -287,7 +322,6 @@ into a buffer called `*edocs*' and switches to that buffer."
|
||||||
(defun edocs--generate-batch-1 (file)
|
(defun edocs--generate-batch-1 (file)
|
||||||
"Generate docs for FILE."
|
"Generate docs for FILE."
|
||||||
(with-current-buffer (find-file file)
|
(with-current-buffer (find-file file)
|
||||||
(eval-buffer)
|
|
||||||
(edocs-generate)
|
(edocs-generate)
|
||||||
(write-file (concat (file-name-sans-extension file) ".html"))))
|
(write-file (concat (file-name-sans-extension file) ".html"))))
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue