Table Of Contents

This Page

About

CLDomain is an extension for the Sphinx documentation generation tool that allow sphinx to generate documentation for Common Lisp libraries.

Hyperspec is a cross referencing extension that supports linking to the hyperspec.

Installation

Requirements

Download

Releases are hosted on github or pypi. The source is also available.

pip install sphinxcontrib-cldomain

Configuration

Edit you conf.py file and add CLDomain and Hyperspec to your enabled extensions.

extensions.extend(['sphinxcontrib.cldomain',
                   'sphinxcontrib.hyperspec'])

System symbols to load

The path to each package needs to the lisp_packages configuration option. In this example the conf.py is in a doc directory and the ASD file is in the parent directory.

The valid keys for each of the systems in the systems dict:

name
The name of the system to load.
path
The path to the system.
packages
A list of the packages to extract symbol information from.
from os.path import join, dirname, realpath
cl_systems = [{"name": "cl-git",
               "path": join(dirname(realpath(__file__)), "../")),
               "packages": ["cl-git"]}]

Quicklisp Location

To set the location of quicklisp in conf.py add a quicklisp variable with the value set to it’s location.

from os.path import expandvars
cl_quicklisp = expandvars('$HOME/quicklisp/')

LISP to use

To configure a specific lisp executable search order use.

cl_lisps = "sbcl ecl"

Documentation

All directives support the nodoc option that will prevent them from pulling the documentation string from Common Lisp. Argument lists and specializers will still be printed:

.. cl:macro:: example-macro
   :nodoc:

   No documentation
macro example-macro

No documentation

Package

.. cl:package:: symbol-name

The cl:package directive specifies the package that all the subsequent directives will look up when trying to resolve a symbol.:

.. cl:package:: sphinxcontrib.cldomain.doc

Variable

.. cl:variable:: symbol-name

The cl:variable directive will resolve the arguments and documentation from the common lisp definition:

.. cl:variable:: *example-variable*

Example:

variable *example-variable*

This is an example variable.

extra description can be appended to further explain the functionality. This doesn’t need to appear in the lisp code. Instead it can be added to the rst files and it will be appended to the documentation.

Function

.. cl:function:: symbol-name

The cl:function directive will resolve the arguments and documentation from the common lisp definition:

.. cl:function:: example-function

Example:

function (example-function arg1 arg2 &optional (arg3 (function sort)) &key (kw *example-variable*))

The CL Domain will try and convert any uppercase symbols into reference for example EXAMPLE-FUNCTION, EXAMPLE-GENERIC or a hyperspec link LIST. Any unmatched symbols are converted to literals as is ARG1, ARG2 and ARG3. Explicit package references will also help resolve symbol sources CAR. Keywords are also detected for example :KEYWORD.

Macro

.. cl:macro:: symbol-name

The cl:macro directive will resolve the arguments and documentation from the common lisp definition:

.. cl:macro:: example-macro

Example:

macro (example-macro (arg1 arg2) &body arg3)

The CL Domain will try and convert any uppercase symbols into reference for example EXAMPLE-FUNCTION or a hyperspec link LIST. Any unmatched symbols are converted to literals as is ARG1, ARG2 and ARG3. Explicit package references will also help resolve symbol sources CDR. Keywords are also detected for example :TEST.

Class

.. cl:class:: symbol-name

The cl:function directive will resolve the arguments and documentation from the common lisp definition:

.. cl:class:: example-class

Example:

type example-class

An example class.

Generics

.. cl:generic:: symbol-name

The cl:generic directive will resolve the arguments and documentation from the common lisp definition. It will also accumulate a list of the specialises and link to the types that this generic specialises on.:

.. cl:generic:: example-generic

Example:

generic (example-generic arg1 arg2 &optional arg3)

A test generic function.

Specializers:

Methods

.. cl:method:: symbol-name (specializer)

The cl:method directive will resolve the arguments and documentation from the common lisp dbenigntion:

.. cl:method:: example-generic example-class :test

For the time being all specializing arguments that aren’t in the current package need to be qualified with a package. E.g common-lisp:t

If you would like to prevent the method from resolving to the generics forms documentation string this can be suppressed using the noinherit option like:

.. cl:method:: example-generic example-class :test
   :noinherit:

Example:

method (example-generic (arg1 example-class) (arg2 :test) &optional arg3)

The CL Domain will try and convert any uppercase symbols into reference for example EXAMPLE-FUNCTION or a hyperspec link LIST. Any unmatched symbols are converted to literals as is ARG1, ARG2 and ARG3. Explicit package references will also help resolve symbol sources CDR. Keywords are also detected for example :TEST.

Specializers:

Multiple Packages

.. cl:function:: symbol-name

The cl:function directive will resolve the arguments and documentation from the common lisp definition:

.. cl:package:: sphinxcontrib.cldomain.doc-alt

.. cl:function:: example-function

Example:

function (example-function arg1 arg2 &optional (arg3 (function sort)) &key (kw *example-variable*))

Symbols can be documented from multiple packages. References to symbols be resolved in the context of the current package for example EXAMPLE-FUNCTION will resolve to the SPHINXCONTRIB.CLDOMAIN.DOC-ALT symbol.

Changelog

Release 0.13 06-09-2015

  • updated com.dvlsoft.clon to net.didierverna.clon.

Release 0.12 24-02-2015

  • fixed argument generation bug.

Release 0.11 30-12-2014

  • support loading symbol information from multiple packages.

Release 0.10 12-06-2014

  • added back parentheses to parameter lists.
  • added type information to parameter list of methods.
  • added links to other methods from a method docstring.
  • fixed bug with macro documentation strings.
  • added better keyword detection in documentation strings.
  • fixed bug where symbols at the end of documentation strings were ignored.

Release 0.9 10-02-2014

  • fixed problem with version number generation.

Release 0.8 10-02-2014

  • fixed bug with lisps argument.
  • removed dependency on swank.
  • remove specializers symbols package if it’s the current package.

Release 0.7 12-06-2013

  • started to make internals more modular.
  • print specialisation for methods.
  • add links to method specializers.
  • added methods to index.

Release 0.6 22-04-2013

  • added more documentation.
  • added better error handling when json fails to parse.
  • methods can now pull documentation from their generic.

Release 0.5 20-04-2013

  • inherit environment when calling subprocesses.
  • better handling of symbols in doc strings.

Release 0.4 19-04-2013

  • fixed some packaging bugs.
  • made the data model more tolerant to missing symbols.
  • fixed symbol resolving bug.
  • added output of unused symbols.

Release 0.3 16-04-2013

  • cleaned up specializer output.
  • fixed bug when rendering specializers that have the form :KEYWORD SYMBOL.
  • updated documentation.
  • split out package code from lisp program.

Release 0.2 14-04-2013

  • link between generics and specializers.
  • ignore symbols in documentation if they are in the arg list.
  • better Quicklisp support.
  • handling of symbols that boarder on punctuation.

Release 0.1 UNRELEASED

  • initial prototype