Commit bb423c64 authored by Nikodemus Siivola's avatar Nikodemus Siivola

documentation baby-steps

 * Default doc/Makefile command now generates all docs and cleans up
   temporary files.

 * Generate info as well, and use makeinfo to generate the html.

 * Spit out a ifnottex.include for @&key macros, etc for the benefit
   of makeinfo.

 * Clean up &WHOLE and &ENVIRONMENT from the lambda-lists.

 * MAKE-CIRCULAR-LIST was documented twice, oops.
parent 829db7c7
.PHONY: clean html pdf .PHONY: clean html pdf include clean-include clean-crap info doc
clean: doc: pdf html info clean-crap
rm -rf include *.aux *.cp *.fn *.fns *.ky *.log *.pg *.toc *.tp *.tps *.vr *.pdf *.html
clean-include:
rm -rf include
clean-crap:
rm -f *.aux *.cp *.fn *.fns *.ky *.log *.pg *.toc *.tp *.tps *.vr
clean: clean-include
rm -f *.pdf *.html *.info
# Hook into the super sekrit texinfo generator in the SBCL tree -- this is just a quick way
# to bootrap documentation for now.
include: include:
sbcl --eval '(progn (require :asdf) (require :alexandria))' \ sbcl --eval '(progn (require :asdf) (require :alexandria))' \
--load docstrings.lisp \ --load docstrings.lisp \
...@@ -15,4 +21,7 @@ pdf: include ...@@ -15,4 +21,7 @@ pdf: include
texi2pdf alexandria.texinfo texi2pdf alexandria.texinfo
html: include html: include
texi2html alexandria.texinfo makeinfo --html --no-split alexandria.texinfo
info: include
makeinfo alexandria.texinfo
...@@ -72,9 +72,11 @@ terms and conditions: ...@@ -72,9 +72,11 @@ terms and conditions:
@ifnottex @ifnottex
@include include/ifnottex.texinfo
@node Top @node Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
@top sbcl @top Alexandria
@insertcopying @insertcopying
...@@ -166,7 +168,6 @@ terms and conditions: ...@@ -166,7 +168,6 @@ terms and conditions:
@include include/fun-alexandria-lastcar.texinfo @include include/fun-alexandria-lastcar.texinfo
@include include/fun-alexandria-setf-lastcar.texinfo @include include/fun-alexandria-setf-lastcar.texinfo
@include include/fun-alexandria-proper-list-length.texinfo @include include/fun-alexandria-proper-list-length.texinfo
@include include/fun-alexandria-make-circular-list.texinfo
@include include/fun-alexandria-mappend.texinfo @include include/fun-alexandria-mappend.texinfo
@include include/fun-alexandria-map-product.texinfo @include include/fun-alexandria-map-product.texinfo
@include include/fun-alexandria-remove-from-plist.texinfo @include include/fun-alexandria-remove-from-plist.texinfo
......
...@@ -383,6 +383,9 @@ there is no corresponding docstring." ...@@ -383,6 +383,9 @@ there is no corresponding docstring."
(cons (car x) (clean (cdr x) :optional t))) (cons (car x) (clean (cdr x) :optional t)))
((cons (member &key)) ((cons (member &key))
(cons (car x) (clean (cdr x) :key t))) (cons (car x) (clean (cdr x) :key t)))
((cons (member &whole &environment))
;; Skip these
(clean (cdr x) :optional optional :key key))
((cons cons) ((cons cons)
(cons (cons
(cond (key (if (consp (caar x)) (cond (key (if (consp (caar x))
...@@ -824,6 +827,18 @@ package, as well as for the package itself." ...@@ -824,6 +827,18 @@ package, as well as for the package itself."
:if-exists :supersede) :if-exists :supersede)
,@forms)) ,@forms))
(defun write-ifnottex ()
;; We use @&key, etc to escape & from TeX in lambda lists -- so we need to
;; define them for info as well.
(flet ((macro (name)
(let ((string (string-downcase name)))
(format *texinfo-output* "@macro ~A~%~A~%@end macro~%" string string))))
(macro '&allow-other-keys)
(macro '&optional)
(macro '&rest)
(macro '&key)
(macro '&body)))
(defun generate-includes (directory packages &key (base-package :cl-user)) (defun generate-includes (directory packages &key (base-package :cl-user))
"Create files in `directory' containing Texinfo markup of all "Create files in `directory' containing Texinfo markup of all
docstrings of each exported symbol in `packages'. `directory' is docstrings of each exported symbol in `packages'. `directory' is
...@@ -841,6 +856,8 @@ markup, you lose." ...@@ -841,6 +856,8 @@ markup, you lose."
(dolist (doc (collect-documentation (find-package package))) (dolist (doc (collect-documentation (find-package package)))
(with-texinfo-file (merge-pathnames (include-pathname doc) directory) (with-texinfo-file (merge-pathnames (include-pathname doc) directory)
(write-texinfo doc)))) (write-texinfo doc))))
(with-texinfo-file (merge-pathnames "ifnottex.texinfo" directory)
(write-ifnottex))
directory))) directory)))
(defun document-package (package &optional filename) (defun document-package (package &optional filename)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment