mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-21 18:38:08 +01:00
bdb6956afd
With text-quoting-style 'grave keeps "'" and "`" quotes unaltered
for further processing done by this code (regardless of locale...).
The tools that read the reStructuredText markup generated can do
their styling instead.
Added temporary conversions of ' and ` to \001 and \002 so that
's and `s outside of `...' and `...` are converted separately
('s restored back to ' and `s converted to \`).
Both `...' and `...` are finally "converted" to `...` (not ``...``).
https://docutils.sourceforge.io/docs/user/rst/quickref.html documents
that as `interpreted text`:
"The rendering and meaning of interpreted text is domain- or
application-dependent. It can be used for things like index
entries or explicit descriptive markup (like program identifiers)."
Which looks pretty much right.
89 lines
2.8 KiB
EmacsLisp
89 lines
2.8 KiB
EmacsLisp
;;; rstdoc.el --- help generate documentation from docstrings -*-lexical-binding: t-*-
|
|
|
|
;; Copyright (C) 2018 David Bremner
|
|
|
|
;; Author: David Bremner <david@tethera.net>
|
|
;; Created: 26 May 2018
|
|
;; Keywords: emacs lisp, documentation
|
|
;; Homepage: https://notmuchmail.org
|
|
|
|
;; This file is not part of GNU Emacs.
|
|
|
|
;; rstdoc.el 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.
|
|
;;
|
|
;; rstdoc.el 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 rstdoc.el. If not, see <https://www.gnu.org/licenses/>.
|
|
;;
|
|
|
|
;;; Commentary:
|
|
|
|
;; Rstdoc provides a facility to extract all of the docstrings defined in
|
|
;; an elisp source file. Usage:
|
|
;;
|
|
;; emacs -Q --batch -L . -l rstdoc -f rstdoc-batch-extract foo.el foo.rsti
|
|
|
|
;;; Code:
|
|
|
|
(defun rstdoc-batch-extract ()
|
|
"Extract docstrings to and from the files on the command line."
|
|
(apply #'rstdoc-extract command-line-args-left))
|
|
|
|
(defun rstdoc-extract (in-file out-file)
|
|
"Write docstrings from IN-FILE to OUT-FILE."
|
|
(load-file in-file)
|
|
(let* ((definitions (cdr (assoc (expand-file-name in-file) load-history)))
|
|
(text-quoting-style 'grave)
|
|
(doc-hash (make-hash-table :test 'eq)))
|
|
(mapc
|
|
(lambda (elt)
|
|
(let ((pair
|
|
(pcase elt
|
|
(`(defun . ,name) (cons name (documentation name)))
|
|
(`(,_ . ,_) nil)
|
|
(sym (cons sym (get sym 'variable-documentation))))))
|
|
(when (and pair (cdr pair))
|
|
(puthash (car pair) (cdr pair) doc-hash))))
|
|
definitions)
|
|
(with-temp-buffer
|
|
(maphash
|
|
(lambda (key val)
|
|
(rstdoc--insert-docstring key val))
|
|
doc-hash)
|
|
(write-region (point-min) (point-max) out-file))))
|
|
|
|
(defun rstdoc--insert-docstring (symbol docstring)
|
|
(insert (format "\n.. |docstring::%s| replace::\n" symbol))
|
|
(insert (replace-regexp-in-string "^" " "
|
|
(rstdoc--rst-quote-string docstring)))
|
|
(insert "\n"))
|
|
|
|
(defvar rst--escape-alist
|
|
'( ("\\\\='" . "\001")
|
|
("`\\([^\n`']*\\)[`']" . "\002\\1\002") ;; good enough for now...
|
|
("`" . "\\\\`")
|
|
("\001" . "'")
|
|
("\002" . "`")
|
|
("^[[:space:]]*$" . "|br|")
|
|
("^[[:space:]]" . "|indent| "))
|
|
"list of (regex . replacement) pairs")
|
|
|
|
(defun rstdoc--rst-quote-string (str)
|
|
(with-temp-buffer
|
|
(insert str)
|
|
(dolist (pair rst--escape-alist)
|
|
(goto-char (point-min))
|
|
(while (re-search-forward (car pair) nil t)
|
|
(replace-match (cdr pair))))
|
|
(buffer-substring (point-min) (point-max))))
|
|
|
|
(provide 'rstdoc)
|
|
|
|
;;; rstdoc.el ends here
|