# HG changeset patch # User Steve Losh # Date 1458309004 0 # Node ID 2daf5fb2fe92a7e495644eac87949b8ddb7219a2 # Parent ae2b13a9a629dfd85d87e1c5838a63ed24fc712e Add API documentation building diff -r ae2b13a9a629 -r 2daf5fb2fe92 Makefile --- a/Makefile Fri Mar 18 12:09:36 2016 +0000 +++ b/Makefile Fri Mar 18 13:50:04 2016 +0000 @@ -1,6 +1,8 @@ .PHONY: test pubdocs +sourcefiles = $(shell ffind --full-path --dir src --literal .lisp) docfiles = $(shell ls docs/*.markdown) +apidoc = docs/03-reference.markdown test: sbcl --noinform --load test/run.lisp --eval '(quit)' @@ -8,6 +10,9 @@ src/utils.lisp: src/make-utilities.lisp cd src && sbcl --noinform --load make-utilities.lisp --eval '(quit)' +$(apidoc): $(sourcefiles) docs/api.lisp + sbcl --noinform --load docs/api.lisp --eval '(quit)' + docs: docs/build/index.html docs/build/index.html: $(docfiles) diff -r ae2b13a9a629 -r 2daf5fb2fe92 docs/03-reference.markdown --- a/docs/03-reference.markdown Fri Mar 18 12:09:36 2016 +0000 +++ b/docs/03-reference.markdown Fri Mar 18 13:50:04 2016 +0000 @@ -1,2 +1,70 @@ -Reference -========= +# API Reference + +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. + +[TOC] + +## Package BONES.PAIP + +Test? + +### \*CHECK-OCCURS\* (variable) + +Whether to perform an occurs check. + +### CLEAR-DB (function) + + (CLEAR-DB) + +### FACT (macro) + + (FACT &REST BODY) + +### FAIL (variable) + +Failure to unify + +### NO-BINDINGS (variable) + +A succesful unification, with no bindings. + +### QUERY (macro) + + (QUERY &REST GOALS) + +Perform the query interactively. + +### QUERY-ALL (macro) + + (QUERY-ALL &REST GOALS) + +Perform the query and automatically show all results. + +### QUERY-ONE (macro) + + (QUERY-ONE &REST GOALS) + +Perform the query and just show the first result. + +### RETURN-ALL (macro) + + (RETURN-ALL &REST GOALS) + +### RETURN-ONE (macro) + + (RETURN-ONE &REST GOALS) + +### RULE (macro) + + (RULE &REST CLAUSE) + +### UNIFY (function) + + (UNIFY X Y &OPTIONAL (BINDINGS NO-BINDINGS)) + +Unify the two terms and return bindings necessary to do so (or FAIL). + diff -r ae2b13a9a629 -r 2daf5fb2fe92 docs/api.lisp --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/api.lisp Fri Mar 18 13:50:04 2016 +0000 @@ -0,0 +1,126 @@ +(let ((*standard-output* (make-broadcast-stream))) + (ql:quickload "docparser")) + +(defparameter *index* + (docparser:parse :bones)) + +(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))) + + +;;;; 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)))) + +(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)) + +(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. + +") + (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) + diff -r ae2b13a9a629 -r 2daf5fb2fe92 package.lisp --- a/package.lisp Fri Mar 18 12:09:36 2016 +0000 +++ b/package.lisp Fri Mar 18 13:50:04 2016 +0000 @@ -4,6 +4,7 @@ (defpackage #:bones.paip (:use #:cl #:defstar #:bones.utils) + (:documentation "Test?") (:export ;; Unification, constants