This is an add-on to the Sphinx documentation system which allows using of information about Common Lisp packages in the documentation.
Initially, Sphinx was created for Python’s documentation and now it is widely used not only for python libraries but also for many other languages.
Sphinx uses reStructured text markup language which is extensible. You can write your own extensions in Python to introduce new building blocks, called “roles”.
sphinxcontrib-cldomain consists of two parts. The first part is a python extension to the Sphinx which adds an ability to render documentation for CL functions, methods and classes. The second - a command-line docstring extractor, written in CL.
Initially, cldomain was created by Russell Sim, but at some moment I’ve forked the repository to port it to the newer Sphinx, Python3 and Roswell.
The coolest feature of the cldomain is its ability to mix handwritten
documentation with docstring. The second - cross-referencing. You can
link between different docstrings and chapters of the documentation.
Today I will not show you any code snippets. Instead, I’ve created an example repository with a simple Common Lisp system and documentation:
https://cl-doc-systems.github.io/sphinxcontrib-cldomain/
This example includes a GitHub workflow to update the documentation on a push to the main branch and can be used as a skeleton for you own libraries.
The main thing I dislike in Sphinx and cldomain is the Python :( Other cons are the complexity of the markup and toolchain setup.
In the next few posts, I’ll review a few other documentation tools for Common Lisp and try to figure out if they can replace Sphinx for me.
I think we as CL community must concentrate our efforts to improve the documentation level of our software and choosing the best setup which can be recommended for everybody is the key.