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

function (foo first &key (other 100500))

This is example function.

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

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

This is very useful because you can provide additional examples:

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

Or insert some graphics:

http://placekitten.com/200/300

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

(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:

(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 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 example/utils package:

function (do-the-job first second)

The function does the job.

It concatenates first and second arguments calling internal function concat.

On this multiline we’ll check how does documentation system processes docstrings.

By the way, pay attention at the second paragraph where I’ve used reStructured text format to make the word “concatenates” bold.

Also, we can reference some parts of the documentation. Read more about cross referencing in the Handwritten documentation chapter.

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.