[ckan-dev] Action API docstrings and CKAN docstring standards

[Sean Hammond]

Hey, I've added docstrings to almost all of the logic.action functions
and merged them into master, and replaced the old action API reference
with these docstrings pulled by autodoc. They could still be improved*
but I wanted to get them merged before anyone modified any of the
functions.

Unfortunately autodoc has stopped working on readthedocs again, so I'll
have to get them to fix it again.

* (They could use more examples, and more explanation of some things,
e.g. task_status_show returns a 'task status' but what is a task
status and what is it for? What CKAN feature is this related to?)

If you add or update any logic.action functions, you should also add or
update the docstrings and follow the style of the existing ones.
It'd also be good to start doing these kind of docstrings everywhere
else in CKAN as well.

I've also added a Coding_Standards.rst file to the root of the git repo:

https://github.com/okfn/ckan/blob/master/Coding_Standards.rst

so far it just contains a first stab at some CKAN docstring standards. I
think we should add to it CKAN coding standards for Python (could take
the existing OKF coding standards as a starting point, then add
CKAN-specific stuff) and CKAN commit guidelines (i.e. how to write
commit messages), and merge it with Aron's guidelines for frontend code.

Not sure if a simple rst file in the git root is the best place for
this. I didn't want to put it in the wiki or sphinx because I think
it'll just get buried and forgotten about. Maybe it should be merged
into or just linked from README.rst?

I've been thinking about the CKAN API. It seems important, if we want
people to build apps that interact with CKAN, for it to have a really
complete, solid and well-documented API. I think the foundation is
there, but it might be worth a chunk of developer time to go through the
whole API fixing bugs and adding tests where they're missing, fixing
inconsistencies, etc. Also to rearrange the docs a little, I think they
should just jump straight into the v3 API, and the v1 and v2 API
references should just get a little link somewhere. Right now the API
docs as a whole are quite big and confusing and don't seem very direct.