Hi,
I am about to complete a revision of LLA and I thought I would write some decent documentation. I have most of the documentation in docstrings, though some of general discussions are in ;;; comments in files.
I am looking for a reasonably automatic way of generating documentation (eg texinfo or HTML) from the source. I found many libraries for this on cliki, and instead of trying all of them out, I thought I would ask for advice here.
Portability would be nice is not necessarily a requirement, so tools like sbcl's texinfo are fine too. However, if possible, I would like to put the documentation on the interface and the internal details in separate sections somehow. I would also be interested in including tutorial-like sections with examples.
Thanks,
Tamas
PS.: I have searched the cl-pro and c.l.l archives and found some discussions about this question, but my impression was that a lot of new libraries appeared on the scene in the past few years.
Tamas Papp tkpapp@gmail.com wrote:
I am looking for a reasonably automatic way of generating documentation (eg texinfo or HTML) from the source. I found many libraries for this on cliki, and instead of trying all of them out, I thought I would ask for advice here.
Portability would be nice is not necessarily a requirement
Then, if you don't mind trying an SBCL-only thing, I would of course recommend my Declt package. It generates Texinfo so you can in turn get Info, HTML and PDF output. It takes one function call (with many options) to generate the Texinfo file. Perhaps you can look at an example to see how things are organized and what gets documented.
The Decl reference manual is such an example: http://www.lrde.epita.fr/~didier/software/lisp/declt/reference.pdf
Good luck.
Hi Tamas,
From the looks of it Didier's Declt is far more complete than Tinaa ever was. Also, Declt looks like it's actually maintained (which I hardly have time to do with my own stuff :-(.).
OTOH, Docudown and CL-Markdown provide a non-automated way to write documentation that can produce much a more useful product (IMHO). The great thing about tools like Declt is that they are automated. The bad thing is that the end product is closer to a dictionary than a encyclopedia. Docudown lets you write documentation and easily add in your docstrings. E.g.,
### Introspection
{docs print-tests} {docs map-testsuites} {docs testsuites} {docs testsuite-tests} {docs find-testsuite}
As an example, http://common-lisp.net/project/lift/user-guide.html#function.find-testsuite and http://common-lisp.net/project/lift/user-guide.text for the source.
The ideal, I think, is to use something like Declt for the reference and something like Docudown for the user-guide.
that's my two cents.
On Jul 19, 2011, at 4:48 AM, Tamas Papp wrote:
Hi,
I am about to complete a revision of LLA and I thought I would write some decent documentation. I have most of the documentation in docstrings, though some of general discussions are in ;;; comments in files.
I am looking for a reasonably automatic way of generating documentation (eg texinfo or HTML) from the source. I found many libraries for this on cliki, and instead of trying all of them out, I thought I would ask for advice here.
Portability would be nice is not necessarily a requirement, so tools like sbcl's texinfo are fine too. However, if possible, I would like to put the documentation on the interface and the internal details in separate sections somehow. I would also be interested in including tutorial-like sections with examples.
Thanks,
Tamas
PS.: I have searched the cl-pro and c.l.l archives and found some discussions about this question, but my impression was that a lot of new libraries appeared on the scene in the past few years.
pro mailing list pro@common-lisp.net http://lists.common-lisp.net/cgi-bin/mailman/listinfo/pro
-- Gary Warren King, metabang.com Cell: (413) 559 8738 Fax: (206) 338-4052 gwkkwg on Skype * garethsan on AIM * gwking on twitter
Gary King gwking@metabang.com wrote:
The ideal, I think, is to use something like Declt for the reference and something like Docudown for the user-guide.
Absolutely. Declt is intentionally meant to be a reference manual generator and nothing else. I've never been a fan of litterate programming and always write my user manuals by hand. But you've caught my attention about docudown and cl-markdown. I should have a closer look at what they do.
-
Didier Verna -
Gary King -
Tamas Papp