[pro] generating documentation

[Gary King]

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 at 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