lQuery-Doc is a utility to automate documentation file generation for Common Lisp packages. It uses lQuery to modify an HTML file and add information for functions, macros, methods and so on. The information used to generate this file is obtained through symbol inspection and docstrings. Thanks to Edi Weitz' Documentation-Template for inspiration and hints.
Load lQuery-Doc with ASDF or Quicklisp.
(ql:quickload :lquery-doc)
In order to compile the documentation for a package, an HTML template and some selectors are required. The HTML template file should contain one block that will be emptied and filled with blocks containing the actual documentation. It further requires a base block that will be used to form a documentation block for each symbol/object. This base block can (by default) be filled with the name, type, description and eventually the arguments of the symbol at hand. As such, lQuery-Doc also asks you to specify selectors for the location where this information should be filled in. None of these are required and will simply default to .funcname .functype .funcdesc and .funcargs respectively.
Any symbol can be explicitely excluded from the documentation, or by exclusion of type. To do this, include the symbol into the :exclude key argument of write-documentation. The following special exclusion symbols are recognized: :external, :internal, :inherited, :missing-docstring, :function, :macro, :generic, :method, :constant, :special. By default, all internal symbols are excluded.
A typical call to write-documentation might look something like this:
(write-documentation :package #p"/path/to/template.html" :output-file #p"/path/to/output.html" :exclude '(:internal :method))
In case you want to fill in information into multiple fields, use different selectors or leave something out:
(write-documentation :package #p"/path/to/template.html" :output-file #p"/path/to/output.html" :exclude '(:internal :method) :fields '(:name ("h4" ".name") :desc (".description") :type (".type")))
Sometimes some more fine-grain control is desired (for example adding anchors isn't possible with the default setup). To get control over each documentation node and modify some things by hand, you can either override the documentate-object method directly, or add an :after specializer method. To add the above mentioned functionality, this code snippet would be sufficient:
(defmethod documentate-object :after (template object fields)
($ template ".anchor" (attr :name (symbol-name (nth 0 object)))))
Of course, we could generalize on this use by reading the anchor selector from the fields plist and add more extensions, but this is good enough for a quick fix to demonstrate it. The template object that is passed into the method is always the current dom:node instance to work on. The object variable is the result returned from get-symbol-info and as such is a list containing (in order): symbol, type, scope, docstring, arguments list.
Alternatively, the whole documentate-object function can be bypassed by supplying write-documentation with the :modifier argument. It expects a function that takes the same three arguments as above. This is useful if you want to write your own way of modifying lQuery-Doc's behaviour differently for multiple packages or files.
lQuery-Doc is a sub-project of TyNETv5 ("Radiance"), licensed under the Artistic License 2.0 and ©2013 TymoonNET/NexT, Nicolas Hafner.
This program can be obtained via git on git://git.tymoon.eu/lquery-doc.git. For questions, patches or suggestions, please contact me via email.
DOCUMENTATE-OBJECT
(TEMPLATE OBJECT FIELDS)
Changes the given template node to include all required information stored in object (see get-symbol-info) on the given fields.
GET-SYMBOL-INFO
(SYMBOL)
Gets all necessary information for the symbol. Returns a list containing symbol, type, docstring and args.
WRITE-DOCUMENTATION
(PACKAGE INPUT-FILE &KEY (OUTPUT-FILE INPUT-FILE) (TARGET "#docs")
(TEMPLATE "#template")
(FIELDS
'(:NAME (".funcname") :DESC (".funcdesc") :ARGS (".funcargs") :TYPE
(".functype")))
(EXCLUDE '(:INTERNAL)) (MODIFIER #'DOCUMENTATE-OBJECT) (IF-EXISTS :SUPERSEDE)
(IF-DOES-NOT-EXIST :CREATE))
Writes the documentation for a package into the specified HTML file and writes it back out. target denotes a selector for a container for the resulting HTML nodes. It is emptied before filling. Template is a selector to the template to use for the documentation. The rest is explained in the documentate function.