ryuslash/edocs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
edocs/edocs.el

152 lines
5.8 KiB
EmacsLisp
Raw Normal View History

Initial commit
2013-12-08 16:28:55 +01:00
;;; edocs.el --- Extract documentation from file(s)
;; Copyright (C) 2013 Tom Willemse
;; Author: Tom Willemse <tom@ryuslash.org>
;; Keywords: docs
;; Version: 0.1.0
;; 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
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; 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 <http://www.gnu.org/licenses/>.
;;; Commentary:
Slight improvement of Commentary
2013-12-13 01:58:12 +01:00
;; Generate formatted description of a module. Currently it makes a
;; simple HTML export of the Commentary and all the docstrings in a
;; file. It is meant to be used as a batch operation, like so:
;; emacs -batch -l edocs.el -f edocs-generate-docs file.el
Initial commit
2013-12-08 16:28:55 +01:00
;;; Code:
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(require 'package)
(require 'help-fns)
(defvar edocs-stylesheet-location "style.css"
"Where to find the Cascading Style Sheet for the exported docs.")
(defvar edocs-generate-only-body nil
"Whether to genereate only the body and no header/footer info.")
Initial commit
2013-12-08 16:28:55 +01:00
(defun edocs--list-symbols ()
"Get a list of all symbols in the buffer.
The results also contain a specification of what was found for
each symbol, for example a `defun', `defvar' or `defcustom',
etc."
(let (ls)
(save-excursion
(goto-char (point-min))
(while (re-search-forward
(rx (and bol ?\(
(group (or "defun" "defgroup" "defcustom" "defvar"
"defclass" "defgeneric" "defconst"
"define-minor-mode"))
" "
(group (1+ (not (any space ?\n ?\)))))))
nil :noerror)
(setq ls (cons (cons (buffer-substring-no-properties
(match-beginning 1) (match-end 1))
(buffer-substring-no-properties
(match-beginning 2) (match-end 2))) ls))))
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(reverse ls)))
Initial commit
2013-12-08 16:28:55 +01:00
(defun edocs--get-docs (type name)
"Get docs of TYPE for symbol NAME."
(let ((type (intern type))
(obj (intern name)))
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(cond
((memq type '(defun define-minor-mode))
(cons (format "%s" (or (help-function-arglist obj :preserve-names)
"()"))
(documentation obj)))
((memq type '(defcustom defvar defconst defclass))
(documentation-property obj 'variable-documentation))
((eql type 'defgroup)
(documentation-property obj 'group-documentation))
((eql type 'defgeneric)
(mapcar (lambda (itm)
(cons (format "%s" (cons (list (car (nth 2 itm))
(car itm))
(cdr (nth 2 itm))))
(nth 3 itm)))
(aref (plist-get (symbol-plist obj)
'eieio-method-tree) 2))))))
Initial commit
2013-12-08 16:28:55 +01:00
(defun edocs--get-type-display (type-name)
"Get the display text for TYPE-NAME."
(cond
((string= type-name "defun") "Function")
((string= type-name "define-minor-mode") "Minor mode")
((string= type-name "defgeneric") "Method")
((string= type-name "defclass") "Class")
((string= type-name "defcustom") "Customization option")
((string= type-name "defgroup") "Customization group")
(t type-name)))
(defun edocs-generate ()
"Generate nice-looking documentation for a module or file."
(interactive)
(let ((buffer (get-buffer-create "*edocs*"))
(binfo (package-buffer-info)))
(with-current-buffer buffer
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(unless edocs-generate-only-body
(insert "<!DOCTYPE html>\n"
"<html><head>"
"<link href=\"" edocs-stylesheet-location
"\" rel=\"stylesheet\"></head><body>"))
(insert "<div class=\"container\">"
"<h1>" (aref binfo 0) " <small>&mdash; " (aref binfo 2)
Initial commit
2013-12-08 16:28:55 +01:00
"</small></h1><p>"
(replace-regexp-in-string
";; " "" (replace-regexp-in-string
";;; Commentary:\n+" "" (aref binfo 4)))
"</p>"))
(mapc (lambda (itm)
(let ((docs (edocs--get-docs (car itm) (cdr itm))))
(with-current-buffer buffer
(mapc (lambda (doc)
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(insert "<div>&ndash; "
Initial commit
2013-12-08 16:28:55 +01:00
(edocs--get-type-display (car itm))
" <tt>" (cdr itm) "</tt> "
(if (consp doc) (car doc) "")
"<p>"
(or (if (consp doc)
(replace-regexp-in-string
"\n\n" "</p><p>" (cdr doc))
(replace-regexp-in-string
"\n\n" "</p><p>" doc))
"Not documented.") "</p></div>"))
(if (or (not (listp docs))
(not (listp (cdr docs))))
(list docs)
docs)))))
(edocs--list-symbols))
(with-current-buffer buffer
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(insert "</div>")
(unless edocs-generate-only-body
(insert "</body></html>")))
Initial commit
2013-12-08 16:28:55 +01:00
(switch-to-buffer buffer)))
Update for use with -batch switch - Require the `package' and `help-fns' libraries which aren't loaded when using the `-batch' switch with Emacs. - Add options to specify which style sheet to use and whether to only print the body (so no `<doctype>' or `<html>' etc.) - Reverse the list of symbols to show up in the same order as they appear in the buffer. - Replace `case' with a `cond', I didn't realize `case' was part of the cl-lib. - Add function to be used with the `-batch' switch.
2013-12-09 00:06:34 +01:00
(defun edocs-generate-batch ()
"Generate module docs using batch operations."
(mapc (lambda (file)
(with-current-buffer (find-file file)
(eval-buffer)
(edocs-generate)
(write-file (concat (file-name-sans-extension file) ".html"))))
command-line-args-left))
Initial commit
2013-12-08 16:28:55 +01:00
(provide 'edocs)
;;; edocs.el ends here
Reference in a new issue Copy permalink