[ckan-dev] Action API autodocs

Thu May 3 09:33:44 UTC 2012

> Although autodoc is still not working on readthedocs, I've started an
> autodoc action API reference in this branch:
> 
> https://github.com/okfn/ckan/compare/feature-2345-action-api-autodocs
> 
> Just checkout that branch, build the docs, and open
> build/sphinx/html/api-ref.html in Firefox.
> 
> There's not much in the way of best-practice example of documenting an
> API function yet, although I've done a couple. I'll do more tomorrow
> morning.
> 
> For the syntax for documenting params, types, etc. of a function see:
> 
> http://sphinx.pocoo.org/markup/desc.html#info-field-lists
> 
> This new page is not linked to from the table of contents or anywhere
> yet, when it's done I think it'll replace the existing
> "Model, Search and Action API: Version 3" page with all those horrible
> tables.

Ok, I've now done a few docstrings for action API functions. I have to
stop for a meeting now, I'll do more later but for now these can be
examples to follow. In logic/action/create.py:

vocabulary_create

tag_create

In logic/action/get.py:

user_activity_list_html

package_activity_list_html

group_activity_list_html

recently_changed_packages_activity_list_html

Note that there are other docstrings there already, but I haven't gone
over them yet so they may not be good examples!

I'm using these as a guide:

http://www.python.org/dev/peps/pep-0257/

http://sphinx.pocoo.org/markup/desc.html#info-field-lists

The important points are that a docstring should have:

- One-line summary of function's behaviour

- Optional longer description of behaviour if necessary

- Summary and/or description should mention any side-effects or
  restrictions on when the function can be called, etc.

- Arguments and their types (and say when an arg is optional), using
  :param and :type

- By arguments I mean the keys you have to POST in the JSON dict when
  you call the API, not the actual arguments of the Python function (context
  and data_dict)

- Return and it's type using :return and :rtype

- Any exceptions using :raises

See the ones I've done so far for formatting and how to use :param,
:type etc. I haven't done any examples of :raises yet though, or of
documenting what happens when a function fails if you pass it bad data
etc. I suggest leaving failure conditions for a second-pass.

The summary and description should be written in the form of a command,
e.g. 'Do this', 'Return that', 'Do foo and return bar' etc., not written
as a description e.g. not 'Does than and returns that'.

The summary and description should not reiterate the arguments of the
function as these can be seen from the header but they should mention
the return type which is not in the header.

I'd like to write a proper CKAN docstring conventions and put it on the
wiki or in sphinx or somewhere, but there won't be time before 1.7.