Autogenerated API
=================

``CLDomain`` does not provide a completely automated generation of the API reference.

You have to manually create a file with documentation for you package.

For example, to render the documentation for the :cl:function:`example/app:foo`
you have to add this piece to your documentation:


::

   example/app
   -----------
   
   .. cl:package:: example/app

   .. cl:function:: foo

      You can also provide additional documentation besides the function's docstring.


It will insert into the document a documentation on FOO function:

example/app
-----------

.. cl:package:: example/app

.. cl:function:: foo

   You can also provide additional documentation besides the function's docstring.

   This is very useful because you can provide additional examples:


   .. code-block:: lisp

      (if some
         (foo "blah")
         (foo "minor" 42))

   Or insert some graphics:

   .. image:: http://placekitten.com/200/300


   By the way, pay attention on the foo's docstring:

   .. code-block:: lisp

      (defun foo (first &key (other 100500))
        "This is example function.

      Internally it calls :cl:function:`example/utils:do-the-job`
      to do the real job."
        (example/utils:do-the-job first other))

   Personally, I'm consider this text shift ugly. I'd prefer this formating:

   .. code-block:: lisp

     (defun foo (first &key (other 100500))
       "This is example function.

        Internally it calls :cl:function:`example/utils:do-the-job`
        to do the real job."
       (example/utils:do-the-job first other))

   But cldomain does not smart enough to do deindentation and displays
   the second paragragraph as a quote:

     Internally it calls :cl:function:`example/utils:do-the-job`
     to do the real job.

   Probably I'll contribute this feature soon unless find a more
   suitable documentation system.


example/utils
-------------

We also add documentation on :ref:`example/utils` package:

.. cl:package:: example/utils

.. cl:function:: do-the-job

.. cl:function:: concat                 

   This function is not exported from the package.
   Sphinx will complain like this:

   ::

      WARNING: Can't find symbol EXAMPLE/UTILS:concat

   Also, does not shows the function's docstring.