.. cl:package:: sphinxcontrib.cldomain.doc

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 :ref:`this <variable2>` 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
~~~~
.. code-block:: common-lisp

   (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
~~~~~~
.. cl:package:: sphinxcontrib.cldomain.doc
.. cl:macro:: example-macro
   :nodoc:

   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:

.. rst:role:: cl:function

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

.. rst:role:: cl:generic

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

.. rst:role:: 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: :cl:method:`example-generic method <sphinxcontrib.cldomain.doc:example-generic (sphinxcontrib.cldomain.doc:example-class (eq keyword:test1))>`).

.. rst:role:: cl:macro

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

.. rst:role:: cl:variable

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

.. rst:role:: cl:clos-class

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

.. rst:role:: cl:clos-slot

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



.. rst:role:: cl:symbol

   References a symbol, such as ``:cl:symbol:example-function`` (link: :cl:symbol:`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 :ref:`cl:function: example<hyperspec_example>` has an example of Hyperspec-ing in its example code.