Page 1 of 2

Auto documentation for lisp?(output html, prefered)

PostPosted: Sat Feb 14, 2009 6:47 am
by Jasper
Is there any automatic documentation maker for lisp? Preferably one that produces simple documentation that can be viewed with simple web browsers, like html. A plus point is extensibility; it being able to recognize some s-expressions and add documentation based on that.

Maybe more generally, a documentation maker for files with trees like that of lisp in it. For which you can then recognize macros for which you want documentation.(And some default ones, like defun, defgeneric, defstruct, defpackage.) And something for per-file documentation.

Edit: that does not sound too hard, i might make it myself if it doesn't exist.

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Sat Feb 14, 2009 9:42 pm
by nuntius

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Sun Feb 15, 2009 7:22 pm
by Jasper
Thanks, i'll look into that when i get to improving my projects website. In retrospect, i could have found that myself if i searched better. (Next time search in lisp sites too :))

What i thought was more general, wasn't. Unless you put all the macros in the documenter.

Nice non-acronym, btw.

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Thu Feb 19, 2009 3:31 pm
by findinglisp

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Wed Mar 18, 2009 3:12 pm
by Jasper
nuntius wrote:Take a look at http://common-lisp.net/project/tinaa/
I hit a problem, somewhat like this guy.. At least one of the downloads for dependencies 404-ed now trying to document, also had to skip a tonne of gpg checks. All in all it says "METABANG.UTILITIES:DIRECTORY-NAME-P is undefined.".. Edit: ok, i decided just define it to return T, now it says it doesn't know a variable IT.

And how do i get documentation-template to actually list anything? I assume you know that with auto-documentation, that it will list me all the functions with their arguments, doc-strings. Stuff like (optionally) links to the actual files,(Edit: it can't know that one from the package, probably) how the functions relate(or maybe even diagrams of that) and all are great plusses. (But i will settle for a lot less for the moment.)

Edit: Ok found out how to get the latter to document.. i didn't export the symbols. (Being sloppy with lang-lisps packages..) documentation-template seems good now. (Does show that it is a quick hack, though. Not much control.)

Thanks for the links :)

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Wed Mar 18, 2009 8:39 pm
by nuntius
Jasper wrote:
nuntius wrote:Take a look at http://common-lisp.net/project/tinaa/
I hit a problem, somewhat like this guy.. At least one of the downloads for dependencies 404-ed now trying to document, also had to skip a tonne of gpg checks. All in all it says "METABANG.UTILITIES:DIRECTORY-NAME-P is undefined.".. Edit: ok, i decided just define it to return T, now it says it doesn't know a variable IT.


Yeah, ASDF-install is not the most reliable of systems. There's a fair chance it would work if you upgraded metatilities by hand.
http://common-lisp.net/project/metatilities-base/
http://common-lisp.net/project/metatilities/

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Thu Mar 19, 2009 8:49 am
by Jasper
Hmm, no cigar. I tried -latest too. It said i didnt have permission, so i ran sudo emacs(i shouldn't have to), but still same problem, without having to accept anything.

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Thu Mar 19, 2009 1:34 pm
by Balooga
Jasper wrote:
nuntius wrote:Take a look at http://common-lisp.net/project/tinaa/
I hit a problem, somewhat like this guy..


That was an entertaining link, thanks for posting :) I am bemused that Common Lisp is so good at some things, and yet so utterly crap at others. However that being said, most CL projects have a single developer. There are very few projects have more than two active developers. So testing a package in more than a single configuration is just not very feasible.

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Sat Mar 21, 2009 5:38 am
by Jasper
It might be better to 'ship' libraries with all the dependencies packaged in then making it harder to use by having to chase broken dependencies down, imo. Of course, you have to check once in a while whether you can update the libraries you use to the newest versions of them..

Maybe implementations should also ship some more libraries along with them, memory is cheap, and most of these libraries are rather small. tinaa tarball is 84 KB, i mean, websites are larger then that. Most people don't like chasing around libraries.

Re: Auto documentation for lisp?(output html, prefered)

PostPosted: Sat Mar 21, 2009 5:55 am
by dmitry_vk
Jasper wrote:It might be better to 'ship' libraries with all the dependencies packaged in then making it harder to use by having to chase broken dependencies down, imo. Of course, you have to check once in a while whether you can update the libraries you use to the newest versions of them..

Maybe implementations should also ship some more libraries along with them, memory is cheap, and most of these libraries are rather small. tinaa tarball is 84 KB, i mean, websites are larger then that. Most people don't like chasing around libraries.

I guess that using a propert package system (like gentoo's portage or debian's apt) is a better approach. On gentoo, I did not have problems with installing lisp libraries.