[ckan-dev] API docs update

[Sean Hammond]

Thanks Adria,

I moved the Search API and Util API into the Legacy API chapter. Some of
the Util API functions are still being used in the CKAN frontend, but I
think for consistency's sake we should call them legacy and aim to get
rid of them from the frontend of replace them with action functions. I
might look into properly deprecating all these legacy API functions in
the code too.

So the table of contents now goes:

- The CKAN APIs
  - The Action API
  - The Datastore API
  - (Insert The Storage API here?)
  - The Legacy APIs

And if you go to the Legacy APIs chapter, only then do you see:

- API Versions 1 & 2
- The Model (i.e. rest) API
- The Search API
- The Util API
- HTTP Status Codes

Which is starting to become a lot clearer than what we currently have:

http://docs.ckan.org/en/latest/index.html#the-ckan-api

I'm still thinking it would be nice to have just "The CKAN API" and not
the Action, Datastore and Storage APIs, just for the sake of consistency
and simplicity. Currently for example, the six different APIs that we
have all behave inconsistently w.r.t. to API version numbers. They're
each documented separately and differently as well. It's pretty
confusing. Just one page the documents the whole API would be nice and
easy.

As you say this is partially just a question of semantics, so I might
look to see if the DataStore and Storage API docs can simply be merged
into the Action API docs rather than each having its own page.