Auto documentation for lisp?(output html, prefered)

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.

Take a look at http://common-lisp.net/project/tinaa/

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.

Try: http://weitz.de/documentation-template/

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

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/

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.

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.

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.

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.

I use clbuild, it can update everything in an easy way - you ask for updating a lib, it updates all of it's dependencies, just like a package manager. I don't think shipping dependencies together is the best answer anyway, but the problem is asdf-install.

If certain sources 404, i can hardly blame asdf for that. Asdf itself might have problems, but maybe the servers hosting the files need to have backups.. Thanks for the link, i'll probably try it at some point.

I think the real issue here is that you need a centralized repository to store all this stuff. ASDF-INSTALL, is, IMO, broken, because it has too many dependencies on various systems. In particular, it depends on Cliki and all the various individual web sites that host each of the packages. Cliki serves as the master catalog, and then each package is served by whatever means the original creator of the package wants to use. If a site goes down or somebody gets lazy and lets their domain name expire, it breaks all the other ASDF-INSTALL packages that depend on a package that goes away.

IMO, what's needed is ultimately something like CPAN. The virtue of systems like CPAN is that once a module is uploaded, it remains available to everybody in whatever state it is in as long as required. The author can get lazy, go off-grid for months, or even die and the system continues to function as long as CPAN itself remains up and running.

Perhaps Mudballs will become something like CPAN for CL. I haven't tried using it myself yet, but it looks pretty nice. Hopefully the maintainer will not get bored and drop this project... alas, package management systems are rather tedious.

Mudballs, as much as I understand, is a replacement for ASDF, not only ASDF-install. I have nothing against it, but I don't have any reasons to abandon ASDF itself, and almost all projects already use ASDF, which means everyone have it already installed and configured. The combination clbuild+asdf seems perfect for me.

gugamilare wrote:Mudballs, as much as I understand, is a replacement for ASDF, not only ASDF-install.

This is a quote from the mudballs site:

Mudballs primary purpose is not System Definition but Repeatable System Distribution.

So it is not just a replacement for ASDF.