# HG changeset patch # User Steve Losh # Date 1458754982 0 # Node ID 9d90efbd87878462e1bfefcbbc2121074fe16af2 # Parent 3729fdede843824a391d0aab8678a443187760f5 Factor out cl-d-api garbage diff -r 3729fdede843 -r 9d90efbd8787 docs/03-reference.markdown --- a/docs/03-reference.markdown Tue Mar 22 16:46:29 2016 +0000 +++ b/docs/03-reference.markdown Wed Mar 23 17:43:02 2016 +0000 @@ -2,9 +2,11 @@ The following is a list of all user-facing parts of Bones. -If there are backwards-incompatible changes to anything listed here, they will be noted in the changelog and the author will feel bad. +If there are backwards-incompatible changes to anything listed here, they will +be noted in the changelog and the author will feel bad. -Anything not listed here is subject to change at any time with no warning, so don't touch it. +Anything not listed here is subject to change at any time with no warning, so +don't touch it. [TOC] @@ -82,7 +84,7 @@ (UNIFY! X Y) -Destructively unify two expressions. +Destructively unify two expressions, returning whether it was successful. Any variables in `x` and `y` may have their bindings set. diff -r 3729fdede843 -r 9d90efbd8787 docs/api.lisp --- a/docs/api.lisp Tue Mar 22 16:46:29 2016 +0000 +++ b/docs/api.lisp Wed Mar 23 17:43:02 2016 +0000 @@ -1,126 +1,24 @@ -(let ((*standard-output* (make-broadcast-stream))) - (ql:quickload "docparser")) - -(defparameter *index* - (docparser:parse :bones)) +(ql:quickload "cl-d-api") (defparameter *document-packages* (list "BONES.PAIP")) - -;;;; From the CL Cookbook -(defun replace-all (string part replacement &key (test #'char=)) - "Returns a new string in which all the occurences of the part -is replaced with replacement." - (with-output-to-string (out) - (loop with part-length = (length part) - for old-pos = 0 then (+ pos part-length) - for pos = (search part string - :start2 old-pos - :test test) - do (write-string string out - :start old-pos - :end (or pos (length string))) - when pos do (write-string replacement out) - while pos))) - +(defparameter *output-path* + #p"docs/03-reference.markdown" ) -;;;; Documentation Utils -(defun get-doc (package-name symbol-name) - (elt (docparser:query *index* - :package-name package-name - :symbol-name symbol-name) - 0)) -(defun get-package-doc (package-name) - ;; good god, lemon - (docparser::find-package-index *index* package-name)) - - -;;;; Markdown Rendering -(defun render-package-header (package-name) - (format t "## Package ~A~%~%" - (replace-all package-name "*" "\\*"))) - -(defun render-package-docstring (package-name) - (let ((package-docstring - (docparser::package-index-docstring (get-package-doc package-name)))) - (when package-docstring - (format t "~A~%~%" package-docstring)))) - -(defun render-symbol-header (symbol-name extra) - (format t "### ~A~A~%~%" - (replace-all symbol-name "*" "\\*") - extra)) - -(defun render-docstring (node) - (let ((documentation (docparser:node-docstring node))) - (when documentation - (format t "~A~%~%" documentation)))) +(defparameter *header* + "The following is a list of all user-facing parts of Bones. -(defun render-lambda-list (node) - (format t " ~A~%~%" - (cons (docparser:node-name node) - (docparser:operator-lambda-list node)))) - -(defgeneric render-documentation (node symbol-name)) - - -(defmethod render-documentation ((node docparser:documentation-node) symbol-name) - (render-symbol-header symbol-name "") - (format t "`~A`~%~%" (class-of node)) - (render-docstring node)) - -(defmethod render-documentation ((node docparser:variable-node) symbol-name) - (render-symbol-header symbol-name " (variable)") - (render-docstring node)) - -(defmethod render-documentation ((node docparser:function-node) symbol-name) - (render-symbol-header symbol-name " (function)") - (render-lambda-list node) - (render-docstring node)) +If there are backwards-incompatible changes to anything listed here, they will +be noted in the changelog and the author will feel bad. -(defmethod render-documentation ((node docparser:macro-node) symbol-name) - (render-symbol-header symbol-name " (macro)") - (render-lambda-list node) - (render-docstring node)) - - -;;;; Documentation Sections -(defun document-symbol (package-name symbol) - (let* ((symbol-name (symbol-name symbol)) - (doc-node (get-doc package-name symbol-name))) - (render-documentation doc-node symbol-name))) - -(defun document-package (package-name) - (render-package-header package-name) - (render-package-docstring package-name) - (let ((symbols (loop :for s :being :the external-symbol :of package-name - :collect s))) - (mapc #'(lambda (symbol) - (document-symbol package-name symbol)) - (sort symbols #'string-lessp :key #'symbol-name)))) - -(defun document-header () - (format t "# API Reference~%~%") - ; (format t "API reference for Bones.~%~%") - (format t "The following is a list of all user-facing parts of Bones. - -If there are backwards-incompatible changes to anything listed here, they will be noted in the changelog and the author will feel bad. - -Anything not listed here is subject to change at any time with no warning, so don't touch it. +Anything not listed here is subject to change at any time with no warning, so +don't touch it. ") - (format t "[TOC]~%~%")) - -;;;; Main -(defun main () - (with-open-file (*standard-output* #p"docs/03-reference.markdown" - :direction :output - :if-exists :supersede) - (document-header) - (mapc #'document-package *document-packages*))) - - -(main) - +(d-api:generate-documentation + :bones + *output-path* + *document-packages* + *header*)