Auto documentation for lisp?(output html, prefered)

Discussion of Common Lisp
Jasper
Posts: 209
Joined: Fri Oct 10, 2008 8:22 am
Location: Eindhoven, The Netherlands
Contact:

Auto documentation for lisp?(output html, prefered)

Post by Jasper » Sat Feb 14, 2009 6:47 am

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.

nuntius
Posts: 538
Joined: Sat Aug 09, 2008 10:44 am
Location: Newton, MA

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

Post by nuntius » Sat Feb 14, 2009 9:42 pm


Jasper
Posts: 209
Joined: Fri Oct 10, 2008 8:22 am
Location: Eindhoven, The Netherlands
Contact:

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

Post by Jasper » Sun Feb 15, 2009 7:22 pm

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.

findinglisp
Posts: 447
Joined: Sat Jun 28, 2008 7:49 am
Location: Austin, TX
Contact:

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

Post by findinglisp » Thu Feb 19, 2009 3:31 pm

Cheers, Dave
Slowly but surely the world is finding Lisp. http://www.findinglisp.com/blog/

Jasper
Posts: 209
Joined: Fri Oct 10, 2008 8:22 am
Location: Eindhoven, The Netherlands
Contact:

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

Post by Jasper » Wed Mar 18, 2009 3:12 pm

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 :)

nuntius
Posts: 538
Joined: Sat Aug 09, 2008 10:44 am
Location: Newton, MA

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

Post by nuntius » Wed Mar 18, 2009 8:39 pm

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/

Jasper
Posts: 209
Joined: Fri Oct 10, 2008 8:22 am
Location: Eindhoven, The Netherlands
Contact:

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

Post by Jasper » Thu Mar 19, 2009 8:49 am

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.

Balooga
Posts: 14
Joined: Tue Jul 15, 2008 1:20 pm

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

Post by Balooga » Thu Mar 19, 2009 1:34 pm

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.

Jasper
Posts: 209
Joined: Fri Oct 10, 2008 8:22 am
Location: Eindhoven, The Netherlands
Contact:

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

Post by Jasper » Sat Mar 21, 2009 5:38 am

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.

dmitry_vk
Posts: 96
Joined: Sat Jun 28, 2008 8:01 am
Location: Russia, Kazan
Contact:

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

Post by dmitry_vk » Sat Mar 21, 2009 5:55 am

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.

Post Reply