elispdoc.el

Author: Benjamin Leis benleis1@gmail.com Created: 5 Mar 2024 Version: 0.1 Keywords: tools Homepage: https://github.com/benleis1/elispdoc Package-Requires: (markdown-toc) (org-make-toc)

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 https://www.gnu.org/licenses/.

Commentary:

Simple tool to provide a javadoc like pipeline for elisp files that outputs a markdown or org file made out of comments with interspersed code blocks

This is intended as an alternative to writing a config file in an org file and tangling it where you want the comments and code to be first class but also want to publish documentation built from it. Embed any markdown/org you want in comments and it will render properly in the transformed doc buffer.

Usage: elispdoc-process-elisp-to-doc-buffer (buffername) A new buffer will be created with the transformed code within it.

To determine the output format customize elispdoc-syntax. Its set to markdown by default.

Transforms done:

all code is blocked together
comment prefixes ; are removed
triple comments ;;; are turned into headers
Emacs variables filtered on the first line
Subheaders added for a functions
TOC inserted after Code: comment
TODO: add variable support in headers and sort option for toc

Code:

Table of Contents

elispdoc.el
Commentary:
Code:

Customizable variables

(defvar elispdoc-include-function-headers t  "Boolean indicating whether to add a subheader for each function")
(defvar elispdoc-include-toc t  "Boolean indicating whether to add a table of contents after Code: section")

Map of document mode tokens

(setq elispdoc-markdown-syntax '((flavor . markdown) (begincode . "```") (endcode . "```")
			    (header . "#") (subheader . "##") (beginquote . ">")))

(setq elispdoc-org-syntax '((flavor . org) (begincode . "#+BEGIN_SRC lisp") (endcode . "#+END_SRC")
		       (header . "*") (subheader . "**") (beginquote . "#+BEGIN_QUOTE\n" )
		       (endquote . "#+END_QUOTE")))

Allow the user to pick between markdown, org and any future doc flavors

(defvar elispdoc-syntax elispdoc-markdown-syntax "Mapping used to determine the flavor of the output doc file")

eld--move-start-next-sexp

Jump to the start of the next sexp and return t if successful

(defun eld--move-start-next-sexp ()
  (let ((start (point)))
    (forward-sexp)
    (if (or (eq (point) start) (eobp))
	nil
      (progn 
	(backward-sexp)
	t))))

eld--line-next-sexp

Return line of next sexp or nil if there isn't one but doesn't move the cursor

(defun eld--line-next-sexp ()
  (save-excursion
    (if (eld--move-start-next-sexp) (line-number-at-pos) nil)))

eld--point-next-sexp

Return point of next sexp or nil if there isn't one but doesn't move the cursor

(defun eld--point-next-sexp ()
  (save-excursion
    (if (eld--move-start-next-sexp) (point) nil)))

eld--end-point-next-sexp

Return point at end of next sexp or nil if there isn't one but doesn't move the cursor

(defun eld--end-point-next-sexp ()
  (save-excursion
    (if (eld--move-start-next-sexp)
	(progn (forward-sexp)
	       (point))
      nil)))

eld--function-name-next-sexp

Process the next sexp to find the function name if it exists Built on the fact we can read in expressions and a function is just a list where the first argument is defun return nil if there isn't one

(defun eld--function-name-next-sexp ()
  (save-excursion
    (eld--move-start-next-sexp)
    (if (eobp) nil
      (let ((form (read (current-buffer))))
	(if (and (listp form) (eq 'defun (nth 0 form)))
	    (symbol-name (nth 1 form))
	  nil)))))

eld--function-docstring-next-sexp

Process the next sexp to find the function docstring if it exists Built on the fact we can read in expressions and a function is just a list where the first argument is defun return nil if there isn't one

(defun eld--function-docstring-next-sexp ()
  (save-excursion
    (eld--move-start-next-sexp)
    (if (eobp) nil
      (let ((form (read (current-buffer))))
	(if (and (listp form) (eq 'defun (nth 0 form)) (stringp (nth 3 form)))
	    (nth 3 form)
	  nil)))))

eld--move-start-next-comment

Jump to the start of the next line with a comment or return null (hardcoded comment char)

(defun eld--move-start-next-comment ()
  ;;  (if (re-search-forward "^;" nil t)
  (if (forward-comment 1)
      (progn
	(forward-line -1)
	(beginning-of-line)
	t)
      nil))

eld--line-next-comment

Return line of next line that starts with a comment or nil if there isn't one but doesn't move the cursor (hardcoded comment char)

(defun eld--line-next-comment ()
  (save-excursion
    (if (forward-comment 1)
	(progn
	  (forward-line -1)
	  (line-number-at-pos))
      nil)))

eld--point-next-comment

Return point of next line that starts with a comment or nil if there isn't one but doesn't move the cursor (hardcoded comment char)

(defun eld--point-next-comment ()
  (save-excursion
    (if (forward-comment 1)
	(progn
	  (forward-line -1)
	  (point))
      nil)))

eld--begin-code

Add a begincode quote before the current line

(defun eld--begin-code ()
  (beginning-of-line)
  (insert (alist-get 'begincode elispdoc-syntax) "\n"))

eld--end-code

Add am endcode quote before the current line

(defun eld--end-code ()
  (beginning-of-line)
  (insert (alist-get 'endcode elispdoc-syntax) "\n"))

eld--point-at-end-of-buffer

Return the point at the end of the buffer

(defun eld--point-at-end-of-buffer ()
  (save-excursion
    (end-of-buffer)
    (point)))

eld--uncomment-noncode-block

Uncomment anything between current position and next sexp leaving the point at the end of this region This relies on the built in uncomment-region function

(defun eld--uncomment-noncode-block ()
  (interactive)
  (let ((start (point))
	(comment-pos (eld--point-next-comment))
	(code-pos (or (eld--point-next-sexp) (eld--point-at-end-of-buffer))))

    (when (and comment-pos (< comment-pos code-pos))
      (progn
	(goto-char (- code-pos 1))
	(uncomment-region start code-pos)))))

eld--add-header-to-function

Add a header comment name at the first blank line above it that is also after the start point if no blank line is found insert a new line at start

(defun eld--add-header-to-function (name start &optional docstring)
  (save-excursion
    (eld--move-start-next-sexp)
    (if (re-search-backward "^$" start t)
	(insert "\n;;" (alist-get 'subheader elispdoc-syntax) " " name)
      (progn
	(goto-char start)
	(beginning-of-line)
	(insert "\n;;" (alist-get 'subheader elispdoc-syntax) " " name "\n")
	))
    (when docstring
      (progn
	(insert "\n;;" (alist-get 'beginquote elispdoc-syntax)  docstring "\n")
	(when  (alist-get 'endquote elispdoc-syntax)
	  (insert "\n;;" (alist-get 'endquote elispdoc-syntax))))
	)))

eld--transform-code-block

Process and move past the next sexp

Add a function header if needed
Uncomment anything before the code block begins and then -quote the next code block and leave the cursor at the end of it return t if a block was found o/w nil

(defun eld--transform-code-block ()

  ;; add function headers if enabled
  (when elispdoc-include-function-headers
    (let ((nextfun (eld--function-name-next-sexp))
	  (docstring (eld--function-docstring-next-sexp)))
      (when nextfun
	(eld--add-header-to-function nextfun (point) docstring))))
  
  (eld--uncomment-noncode-block)
  (if (eld--move-start-next-sexp)
      (progn
	(eld--begin-code)
	(forward-sexp)

	;; advance past any code that is before the next comment
	;; when adding function headers also stop at the next defun
	(while (and (eld--line-next-sexp)
		    (or (not elispdoc-include-function-headers) (not (eld--function-name-next-sexp)))
		    (or (not (eld--line-next-comment))
			(< (eld--line-next-sexp) (eld--line-next-comment))))
	  (forward-sexp))

	;; Add end quotes
	(forward-line)
	(eld--end-code)
	t)
    ;; else
    nil))

eld--transform-all-code-blocks

Quote all the code blocks in a buffer

(defun eld--transform-all-code-blocks ()
  (save-excursion
    (beginning-of-buffer)
    (while (eld--transform-code-block) t)
    ;; Deal with trailing comments at the end of the buffer
    (eld--uncomment-noncode-block)))

eld--regex-replace-on-line

Replace a regular expression on the current line

(defun eld--regex-replace-on-line (exp replace)
  (save-excursion
   (beginning-of-line)
   (let ((start (point))
	 (end ()))
     (forward-line)
     (setq end (point))
     (replace-regexp-in-region exp replace start end))))

eld--add-toc-org

Wrapper for using org-make-toc

(defun eld--add-toc-org ()
  ;; directly add the template
  (insert
   ":PROPERTIES:\n"
   ":TOC:      :include descendants :depth 2\n"
   ":END:\n"
   ":CONTENTS:\n"
   ":END:\n")
  (org-make-toc))

eld--add-toc

setup a table of contents using markdown-toc Placed after Code: comment

(defun eld--add-toc ()
  (beginning-of-buffer)
  (if (re-search-forward (concat "^" (alist-get 'header elispdoc-syntax) "\s?Code:") nil t)
      (progn
	(forward-line)
	(let ((flavor (alist-get 'flavor elispdoc-syntax)))
	  (cond ((eq flavor 'markdown) (markdown-toc-generate-toc))
		((eq flavor 'org) (eld--add-toc-org))
		(t (message "No mapping for doc flavor %s" (symbol-name flavor)))
		)))))

elispdoc-process-elisp-to-doc-buffer

Transform the current elisp buffer into a new markdown doc buffer

Main user command to generate the processed buffer

(defun elispdoc-process-elisp-to-doc-buffer (bufname)
  "Transform the current elisp buffer into a new markdown doc buffer"
  (interactive "sNew buffer name:")
  (generate-new-buffer bufname)
  (copy-to-buffer bufname nil nil)
  (with-current-buffer bufname
    (progn
      (lisp-mode)
      ;; remove any emacs file variables on the first line.
      (eld--regex-replace-on-line "\-\*\-.*\-*\-" "")
      ;; Convert any  triple comments to markdown headers 
      (replace-regexp-in-region "^;;;" (concat ";;" (cdr (assoc 'header elispdoc-syntax))) 1 nil)
      ;; Do the regular transform - quoting code and removing comments
      (eld--transform-all-code-blocks)
      ;; Add a note at the end
      (end-of-buffer)
      (insert "\n" (alist-get 'beginquote elispdoc-syntax)
	      " This file was auto-generated by elispdoc.el")
      (when  (alist-get 'endquote elispdoc-syntax)
	(insert "\n"  (alist-get 'endquote elispdoc-syntax)))

      (let ((flavor (alist-get 'flavor elispdoc-syntax)))
	(cond ((eq flavor 'markdown) (markdown-mode))
	      ((eq flavor 'org) (org-mode))
	      (t (error (concat "unsupported document flavor: "
				(symbol-name (cdr (assoc 'flavor elispdoc-syntax))))))))
      ;; Insert a toc after Code: if specified
      (when elispdoc-include-toc
	(eld--add-toc)))))

This file was auto-generated by elispdoc.el

ludamillion/elispdoc