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 and the list of packages to load.
from os.path import join, dirname, realpath, expandvars
# --- CL domain customizations:
#
# cl_systems: The systems and packages from which to extract documentation:
#
# 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.
#
# 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__)), "../"),
"packages": ["my-package-1", "my-package-2"]}]
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.
package
The packages from the system to load documentation and other symbol information.
cl_packages¶
The cl_packages variable contains a list of all the packages to
load symbols for. It can be used instead of the system base object
specified above. It’s really mostly useful for loading the
COMMON-LISP package if that is needed.
# cl_packages: A list of packages that already exist in the lisp image.
cl_packages - ["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 and packages from which to extract documentation:
#
# 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.
#
# 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__)), "../"),
"packages": ["my-package-1", "my-package-2"]}]
# 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