blog/overview-of-documentation-generators/

[utterances-bot]

Overview of Documentation Generators - Lisp journey

I have a simple need: I'd like to generate an html documentation from my code. What options do we have ?I searched for “documentation tool” on Quickdocs: http://quickdocs.org/search?q=documentation%20tool, from which I remove old ones (clod, qbook, manifest).I had two pure Lisp solutions working out of the box, two more are of interest, and there's another non-Lisp of interest.update: just found out that qbook (github mirror)is used for the documentation of Fiveam, which is pretty nice: https://common-lisp.

https://lisp-journey.gitlab.io/blog/overview-of-documentation-generators/

[vindarel]

Also found: http://www.crategus.com/books/atdoc/pages/atdoc.html (example: http://www.crategus.com/books/cl-cffi-gtk/)

[vindarel]

New little on in town: https://github.com/guicho271828/eazy-documentation/

[vindarel]

Another one, with a recent update: http://helambdap.sourceforge.net/

[mmontone]

Hello. FYI, I've been updating QBook a bit.

https://github.com/mmontone/qbook

Added syntax highlighting and much better latex support.

HTML example: https://mmontone.github.io/qbook/ PDF example: https://mmontone.github.io/qbook/qbook.pdf

What I find nice about QBook is that it is kind of a lightweight literate programming system, where Lisp code is not rendered inline, but in separate sections, and that makes the document more pleasant to navigate.

Cheers!

[vindarel]

That's great, thanks for the heads up!

[vindarel]

Another one (not tested): https://github.com/lokedhs/docbrowser a server that generates documentation for the loaded systems on the fly.

from mmontone's thread: https://www.reddit.com/r/lisp/comments/gpxe2p/some_updates_to_the_qbook_lisp_documentation/

Its main page presents a list of all loaded systems. Click on one, and you get a page with two panes, one for the functions and one for the variables. Click on a function to see its source, in context, with line numbers.

An addition could be the ability to search and filter by function name. This makes me think about Ultralisp's symbol search: https://ultralisp.org/

[vindarel]

Yet another one: https://github.com/stefandevai/litterae which looks very good: https://40ants.com/teddy/

[vindarel]

Also to explore: http://melisgl.github.io/mgl-pax/ mixing code and documentation somehow.

[vindarel]

Atdoc: http://www.lichteblau.com/atdoc/doc/ (review: https://github.com/cl-doc-systems/atdoc) Also renders to PDF and Info files.

[BenedictHW]

Thank you for this article! Would not have discovered declt otherwise. The information has become outdated though. Declt does work "out of the box" for me:

(ql:quickload :net.didierverna.declt)
(net.didierverna.declt:declt :project-name :texi-directory "/path/to/project-name/")

then from .texinfo to info/HTML/pdf

cd /path/to/project-name/
makeinfo --pdf project-name.texi

The resulting pdf/HTML is really very pleasant and comprehensive! From the introduction in the documentation:

In addition to ASDF system components and packages, Declt documents the following definitions: constants, special variables, symbol macros, macros, setf expanders, compiler macros, functions (including setf ones), generic functions and methods (including setf ones), method combinations, conditions, structures, classes and types.

The generated documentation includes every possible bit of information that introspecting can provide: documentation strings, lambda lists (including qualifiers and specializers where appropriate), slots (including type, allocation and initialization arguments), definition source file etc.

Every documented item provides a full set of cross-references to related items: ASDF component dependencies, parents and children, classes direct methods, super and subclasses, slot readers and writers, setf expanders access and update functions etc.

Finally, Declt produces exhaustive and multiple-entry indexes for every documented item.

Very exhaustive. Truly the Lisp way of "doing the right thing". And this was with no adapting my project structure either, just using docstrings wherever I can. Let me know how it works for you!

I do believe you and SabraCrolleton (in the unlikely case you haven't seen his work on libraries, https://sabracrolleton.github.io/testing-framework and https://github.com/sabracrolleton/sabracrolleton.github.io) would do a heck of a job if you guys collaborated with the community on Common Lisp library surveying.

Re: declt, some important notes on the 'caveat' docs mention declt working best on SBCL and ASDF > 3.0. But the author is prepping for a major release of declt soon. https://github.com/didierverna/declt/commit/13bb631eaf282a1fb5ebbb30843df6f21bf3983e. The author seems to care a lot about code quality and backwards compatibility. Also declt has zero dependencies as well.

Thanks again for all your work! Keep blogging!

Cheers,

[vindarel]

Hi, thanks for the heads up! (and the kind words)

I tried to generate a HTML documentation but I get errors like

$ makeinfo --html str.texi
makeinfo --html str.texi
str.texi:384: unknown command `ampchar'
str.texi:384: misplaced {
str.texi:384: misplaced }

probably an old version (texi2any (GNU texinfo) 6.5) (didn't google).

I'll keep blogging and I should announce new learning materials shortly© :)