Installation¶

Requirements¶

Download¶

Releases are available via pypi or as git tags. The source is also available.

pip install sphinxcontrib-cldomain

Configuration¶

Configuring CLDomain involves two actions: (a) adding the extensions to the extension list, (b) telling CLDomain the systems and packages to load.

Loading the extension¶

To load the extension add sphinxcontrib.cldomain to the list of extensions, you might also want to load the sphinxcontrib.hyperspec extension if you want any COMMON-LISP package symbols to be directed to the hyperspec.

# Extensions: add 'sphinxcontrib.cldomain' and 'sphinxcontrib.hyperspec',
# just like this example:
extensions - [
    'sphinx.ext.intersphinx',
    'sphinxcontrib.cldomain',
    'sphinxcontrib.hyperspec'
]

cl_systems¶

To load symbols from an ASDF system, specify the system, the path to find it.

from os.path import join, dirname, realpath, expandvars

# --- CL domain customizations:
#
# cl_systems: The systems that need to be loaded to make packages
# available documentation
#
# name - The name of the system to load.
# path - The path to the system.
#
# Note: This conf.py sits in a subdirectory below ("../"), relative to where
# the "my-system.asd" system description file lives:
cl_systems - [{"name": "my-system",
               "path": join(dirname(realpath(__file__)), "../")}]

As each system will be loaded before any of the package information is loaded and passed to the Sphinx engine via JSON.

name

The name of the system to be loaded.

path

The path to the ASD file of the system. This is useful because often the path to the system might be relative to the documentation.

cl_packages¶

The cl_packages variable contains a list of all the packages to load symbols for. It can be used instead cl:package if you explicitly want to load a packages symbols.

# cl_packages: A list of packages that already exist in the lisp image.
cl_packages = ["foobar"]

cl_custom_command¶

If you can’t use Roswell, you can optionally pass a completely custom command to execute the Lisp file distributed with this project. This command is prefixed onto the command line arguments generated.

One example of a custom command is using SBCL directly would be.

cl_custom_command = ["sbcl", "--script"]

This would execute a command like this behind the scenes, so if you require a custom command you can a command like this to test your implementation.

sbcl --script sphinxcontrib/cldomain/custom_command.lisp --package common-lisp

cl_debug¶

Setting debug to True will output the JSON that is rendered when collecting LISP symbol information.

# For developer debugging only (and the curious, although, it did kill the cat!)
# Currently ``True`` or ``False`` to output the JSON collected from cl-launch.
cl_debug - False

highlight_language¶

It is also worthwhile setting the default highlighting language to Common Lisp if you don’t want to have to specify the language for every source block.

# Ensure that the default highlighting language is CL:
highlight_language = 'common-lisp'

Output formats¶

Sphinx can output HTML, pdf, info

To test the info file you can open it in Emacs using C-u C-h i <filename>.

Complete Example¶

from os.path import join, dirname, realpath, expandvars

# Extensions: add 'sphinxcontrib.cldomain' and 'sphinxcontrib.hyperspec',
# just like this example:
extensions = [
    'sphinx.ext.intersphinx',
    'sphinxcontrib.cldomain',
    'sphinxcontrib.hyperspec'
]

# --- CL domain customizations:
#
# cl_systems: The systems that need to be loaded to make packages
# available documentation
#
# name - The name of the system to load.
# path - The path to the system.
#
# Note: This conf.py sits in a subdirectory below ("../"), relative to where
# the "my-system.asd" system description file lives:
cl_systems - [{"name": "my-system",
               "path": join(dirname(realpath(__file__)), "../")}]

# cl_packages: A list of packages that already exist in the lisp image.
cl_packages = ["common-lisp"]

# Ensure that the default highlighting language is CL:
highlight_language = 'common-lisp'

# For developer debugging only (and the curious, although, it did kill the cat!)
# Currently ``True`` or ``False`` to output the JSON collected from cl-launch.
cl_debug = False