Example of Sphinx documentation for a Common Lisp library

This is a small library includes a few functions with docstrings and a handwritten documentation. The purpose is to demonstrate core features of the sphinxcontrib-cldomain library.

The repository can be used as a template for new libraries if you’ve choosen cldomain for documenting your library.

Let’s review features, provided by cldomain.

• Handwritten documentation
• Autogenerated API
• How to build the documentation

Pros & Cons of cldomain

Pros

• reStructured text format has flexible abstraction to extend its functionality. You can add new “roles” to support different types of documentation blocks.

• reStructured text is widely used. It is like markdown, but is more suitable for writing large interlinked documents.

• Sphinx provides builtin term search and also many other extensions are also available. And you can use all of them simultaneously. This can be especially useful if you are documenting the project which involves many programming languages.

• Provides cross-reference helpers.

Cons

• Syntax is more complex than Markdown and requires some time to get familiar with.

• Syntax relies on indentation and sometimes it leads to the problems.

• Sometimes it hard to decrypt Sphinx’s error messages when it doesnt do what you’ve expected.

• CLdomain is complex to setup. But you can use this repository as a skeleton :)

• Sphinx and it’s extensions are written in Python, I’d prefer to use Common Lisp.