Common Lisp docstrings

CLDomain collects the documentation strings for the package-exported symbols in each system enumerated in the cl_systems configuration variable, which CLDomain appends to the symbol’s signature. You can include additional documentation after the directive and it will also get included in the Spinx-generated output. The output template looks like:

type: signature

symbol-docstring

Any additional text described in the RST files.

For an example, follow this link or read on.

Don’t include the docstring: :nodoc:

By default documentation strings will propagate through from symbols declared in Common Lisp, sometimes you’d prefer to provide separate (non-docstring) documentation. That’s what the :nodoc option does.

Argument lists and specializers will still be printed, but can be disabled using other configuration.

For example:

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

  No documentation from the ``example-macro`` documentation string.

Code

(defmacro 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
COMMON-LISP:CDR.  Keywords are also detected for example :TEST."
  arg3)

Output

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

No documentation from the example-macro documentation string.

Cross-references

You can cross reference Lisp entities using the following CLDomain Sphinx roles, which results in a hyperlinked reference to the matching identifier, if found:

:cl:function:

References a function, as in :cl:function:`example-function` (link: example-function).

:cl:generic:

References a generic function, as in :cl:generic:`example-generic` (link: example-generic).

:cl:method:

References a generic-specializing method, as in cl:method:`example-generic method <sphinxcontrib.cldomain.doc:example-generic (sphinxcontrib.cldomain.doc:example-class (eq keyword:test1))>` (link: example-generic method).

:cl:macro:

References a macro, as in :cl:macro:`example-macro` (link: example-macro).

:cl:variable:

References a variable, as in :cl:variable:`*example-variable*` (link: *example-variable*).

:cl:clos-class:

References a CLOS class, as in :cl:clos-class:`example-class` (link: example-class).

:cl:clos-slot:

References a CLOS slot, as in :cl:clos-slot:`slot2 <sphinxcontrib.cldomain.doc:example-class sphinxcontrib.cldomain.doc::slot2>`` (link: slot2).

:cl:symbol:

References a symbol, such as :cl:symbol:example-function (link: example-function).

Hyperspec References

Generating a reference is very easy (and you’ve probably noticed already if you’ve read the Common Lisp code snippets used to generate the examples). To generate a Hyperspec reference:

  1. THE COMMON LISP SYMBOL NAME IS IN ALL CAPS, LIKE LIST OR FORMAT. (No, the documentation isn’t shouting at you. It’s the normal Lisp convention for symbols.

  2. Prefix the symbol name with COMMON-LISP:, e.g., COMMON-LISP:CAR

The cl:function: example has an example of Hyperspec-ing in its example code.