1 ;;; rstdoc.el --- help generate documentation from docstrings -*-lexical-binding: t-*-
3 ;; Copyright (C) 2018 David Bremner
5 ;; Author: David Bremner <david@tethera.net>
6 ;; Created: 26 May 2018
7 ;; Keywords: emacs lisp, documentation
8 ;; Homepage: https://notmuchmail.org
10 ;; This file is not part of GNU Emacs.
12 ;; rstdoc.el is free software: you can redistribute it and/or modify it
13 ;; under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
17 ;; rstdoc.el is distributed in the hope that it will be useful, but
18 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 ;; General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with rstdoc.el. If not, see <https://www.gnu.org/licenses/>.
29 ;; Rstdoc provides a facility to extract all of the docstrings defined in
30 ;; an elisp source file. Usage:
32 ;; emacs -Q --batch -L . -l rstdoc -f rstdoc-batch-extract foo.el foo.rsti
38 (defun rstdoc-batch-extract ()
39 "Extract docstrings to and from the files on the command line"
40 (apply #'rstdoc-extract command-line-args-left))
42 (defun rstdoc-extract (in-file out-file)
43 "Write docstrings from IN-FILE to OUT-FILE"
45 (let* ((definitions (cdr (assoc (expand-file-name in-file) load-history)))
46 (doc-hash (make-hash-table :test 'eq)))
51 (`(defun . ,name) (cons name (documentation name)))
53 (sym (cons sym (get sym 'variable-documentation))))))
54 (when (and pair (cdr pair))
55 (puthash (car pair) (cdr pair) doc-hash))))
60 (rstdoc--insert-docstring key val))
62 (write-region (point-min) (point-max) out-file))))
64 (defun rstdoc--insert-docstring (symbol docstring)
65 (insert (format "\n.. |docstring::%s| replace::\n" symbol))
66 (insert (replace-regexp-in-string "^" " " (rstdoc--rst-quote-string docstring)))
69 (defvar rst--escape-alist
70 '( ("\\\\='" . "\\\\'")
71 ("\\([^\\]\\)'" . "\\1`")
72 ("^[[:space:]\t]*$" . "|br|")
73 ("^[[:space:]\t]" . "|indent| "))
74 "list of (regex . replacement) pairs")
76 (defun rstdoc--rst-quote-string (str)
79 (dolist (pair rst--escape-alist)
80 (goto-char (point-min))
81 (while (re-search-forward (car pair) nil t)
82 (replace-match (cdr pair))))
83 (buffer-substring (point-min) (point-max))))
85 ;;; rstdoc.el ends here