Installation
============

Requirements
------------

* `Sphinx <http://sphinx-doc.org/>`_
* `roswell <https://roswell.github.io/>`_
* `pygments-cl-repl <https://pypi.python.org/pypi/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.

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.

.. code-block:: python

  # 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.

.. code-block:: python

  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 :rst:dir:`cl:package` if you
explicitly want to load a packages symbols.

.. code-block:: python

  # 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.

.. code-block:: python

   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.

.. code-block:: python

  # 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.

.. code-block:: python

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


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
<filename>``.

Complete Example
================

.. 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 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