common-lisp-libraries.readthedocs.io

In case of any inaccuracies, ambiguities or suggestions, please create an issue here.

See the html version of this page, rather than the markdown version for the working links below.

Introduction

Common Lisp documentation - libraries or the HyperSpec - isn't known to be particularly "modern" or "attractive". While those terms are subjective, ease of introduction to a technology does seem to have some objective component to it.

Libraries

Installation

Each of the below libraries (except asdf and quicklisp) can be installed using quicklisp:

(ql:quickload "alexandria") ; for example

See quicklisp - Getting Started for instructions on installing quicklisp.

Optionally, you may want to use trivial-package-local-nicknames for, well, adding package local nicknames.

(ql:quickload :trivial-package-local-nicknames)
(trivial-package-local-nicknames:add-package-local-nickname :a :alexandria)
; OR
(defpackage my-package
  (:use #:cl)
  (:local-nicknames (#:a #:alexandria)))
;;; I'm yet to read up on the naming conventions and the reasons behind those conventions
;;; in the context of systems and packages; some conventions do exist.

Libraries documented so far

The below list of libraries is not even the complete list of defacto libraries. Many more awesome Common Lisp libraries are available at awesome-cl.

Defacto libraries

Not yet defacto

  • numcl - lispy clone of numpy
  • unix-opts - minimalistic command line options parser

*What one might call packages in other languages are called systems in Common Lisp parlance. Instead, the word package in Common Lisp refers to a data structure providing namespacing for symbols. By contrast, a system is a tool to organize a bunch of files, in accordance with dependencies, and specifying how to perform certain actions on the system. A single system may contain multiple packages. See this StackOverFlow answer for a detailed discussion.

Previous Efforts

Documentation efforts have been made at:

  • Quickdocs: While it was up, I didn't particularly like the layout. I want the API at a glance! This can improve! But don't look at me. I'm also not very at ease with full automation without human intervention. As of December 2020, this is down though.

  • Quickref: Frankly, this is just too much. As a user, all I want to know is "What can this library do? And, how do I do it? (What functions, macros or anything is available?)" Therefore, for a user, the only good place I found was the Packages section here. It is, after all, a Reference Manual. Another excuse is, again, that I do want human intervention in documentation.

  • common-lisp.net: Ultimately, this is the place for most everything Common Lisp. And indeed, most of the work here is based on the official documentation. An attempt is made to "simplify" wherever need is felt.

  • CLiki: Again, layout and "at a glance"!

  • UltraSpec: I liked this. The only trouble? It isn't "quick" to build upon.

  • MiniSpec: This looks like a work-in-progress-but-active perhaps-smaller version of UltraSpec. And for the parts that are done, I find this vastly better than CLHS in terms of looks and accessibility.

UltraSpec

I liked (the theme of) UltraSpec. I also liked mkdocs - I am using mkdocs with the pre-provided readthedocs theme. What UltraSpec seems to be good for is larger websites than what is currently here, in that it isn't as straightforward as mkdocs for library-documenters to use it.

Additionally, markdown files and dokuwiki files (the format UltraSpec requires) are interconvertible (but the compatibility is untested) using pandoc. (pandoc is indeed useful for a ton of other file formats!)

mkdocs

As a marketing for mkdocs: mkdocs is as simple as

  • pip install mkdocs # or conda
  • create a .yml configuration file (or copy and edit!)
  • put your markdown files inside docs/ directory (or as mentioned in the .yml file)
  • mkdocs gh-deploy# to deploy on github-pages

Done!

PS: Regardless of the justifications, all I wanted was a documentation site with a "sidebar" that, both, tells the page at glance, and is easy to navigate.