20131106

With a little HEΛP....



I finally managed to push a preliminary version of my documentation generation system to Sourceforge. The project's site (and the links to the git repository) are at https://sourceforge.net/projects/helambdap/. The project's main web page (obviously self-generated) is http://helambdap.sourceforge.net. the git repository can be found there.
You are all welcome to play around with the code (it has a BSD license) and to suggest (better: provide) improvements.
An example of what HEΛP can do with a third party system is here: the documentation generated for the UIOP portability substrate of ASDF3.
The actual call used to generate UIOP's documentation is below (comments follow).

(document #P"asdf/uiop/"
          :documentation-title "UIOP"
          :everything t
          :exclude-files (list #P"/Path/To/asdf3/asdf/uiop/asdf-driver.asd")
          :special-methods-defs-files (list #P"/This/file/here/helambda-asdf3.lisp")
          )

The document function is called on a folder ("asdf/uiop/") with an obvious title. The other arguments have the following meaning:
  • :everything t tells HEΛP to generate documentation pages for everything; these are stored in the dictionary subfolder with file-names which should be relatively obvious. Ordinarily, HEΛP would generate doc pages only for public (i.e., exported) interfaces.
  • :exclude-files is a list of files to forget about; UIOP has one file with an unqualified DEFSYSTEM in, which confuses HEΛP.
  • special-methods-defs-files is a list of files containing specialized definitions to handle a library extra "definition" forms and macros. UIOP has a number of them.

The results are, IMHO, pretty good. Also note that I used HEΛP on the pure set of UIOP files. The actual intended use of HEΛP is to generate documentation of a loaded (and, possibly, compiled) library or system.

So, give it a spin and let me know what you think. If you want, you can subscribe to the mailing lists at the following link: https://sourceforge.net/p/helambdap/mailman/.

HEΛP depends on XHTMΛ. For the time being you have to fetch them directly from the relative sites.  Eventually they will be submitted to Quicklisp.


(cheers)

No comments:

Post a Comment