Installation
============
Requirements
------------
* `Sphinx `_
* `roswell `_
* `pygments-cl-repl `_
Download
--------
Releases are available via `pypi`_ or as `git tags`_. The `source`_ is also available.
.. code-block:: sh
pip install sphinxcontrib-cldomain
.. _git tags: https://git.sr.ht/~rsl/sphinxcontrib-cldomain/refs
.. _pypi: https://pypi.python.org/pypi/sphinxcontrib-cldomain
.. _source: https://git.sr.ht/~rsl/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.
.. _conf_py_block:
.. code-block:: python
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"]}]
# 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
Output formats
==============
Sphinx can output HTML, :download:`pdf <_build/latex/cldomain.pdf>`,
:download:`info <_build/texinfo/cldomain.info>`
To test the ``info`` file you can open it in Emacs using ``C-u C-h i
``.