[ckan-changes] [okfn/ckan] c1c919: [#2345] Little more work on autodoc action API ref

[GitHub]

  Branch: refs/heads/feature-2345-action-api-autodocs
  Home:   https://github.com/okfn/ckan
  Commit: c1c9198a9445f0835d200c812f13318312c1b5e9
      https://github.com/okfn/ckan/commit/c1c9198a9445f0835d200c812f13318312c1b5e9
  Author: Sean Hammond <seanhammond at lavabit.com>
  Date:   2012-05-02 (Wed, 02 May 2012)

  Changed paths:
    M ckan/logic/action/get.py
    M doc/api-ref.rst

  Log Message:
  -----------
  [#2345] Little more work on autodoc action API ref


diff --git a/ckan/logic/action/get.py b/ckan/logic/action/get.py
index 45677ad..5046dc4 100644
--- a/ckan/logic/action/get.py
+++ b/ckan/logic/action/get.py
@@ -1175,7 +1175,7 @@ def user_activity_list(context, data_dict):
     return model_dictize.activity_list_dictize(activity_objects, context)
 
 def package_activity_list(context, data_dict):
-    '''Return a package\'s public activity stream as a list of dicts.'''
+    '''Return a package\'s activity stream as a list of dicts.'''
     model = context['model']
     package_id = data_dict['id']
     query = model.Session.query(model.Activity)
@@ -1186,7 +1186,7 @@ def package_activity_list(context, data_dict):
     return model_dictize.activity_list_dictize(activity_objects, context)
 
 def group_activity_list(context, data_dict):
-    '''Return a group\'s public activity stream as a list of dicts.'''
+    '''Return a group\'s activity stream as a list of dicts.'''
     model = context['model']
     group_id = data_dict['id']
     query = model.Session.query(model.Activity)
@@ -1338,30 +1338,45 @@ def _activity_list_to_html(context, activity_stream):
     return webhelpers.html.literal('\n'.join(html))
 
 def user_activity_list_html(context, data_dict):
-    '''Return an HTML rendering of a user\'s public activity stream.
+    '''Return an HTML rendering of a user's public activity stream.
 
     The activity stream is rendered as a snippet of HTML meant to be included
-    in an HTML page.
+    in an HTML page, i.e. it doesn't have any HTML header or footer.
+
+    :param id: The id or name of the user.
+    :type id: string
+    :returns: The activity stream as HTML.
+    :rtype: string
 
     '''
     activity_stream = user_activity_list(context, data_dict)
     return _activity_list_to_html(context, activity_stream)
 
 def package_activity_list_html(context, data_dict):
-    '''Return an HTML rendering of a package\'s public activity stream.
+    '''Return an HTML rendering of a package's activity stream.
 
     The activity stream is rendered as a snippet of HTML meant to be included
-    in an HTML page.
+    in an HTML page, i.e. it doesn't have any HTML header or footer.
+
+    :param id: The id or name of the package.
+    :type id: string
+    :returns: The activity stream as HTML.
+    :rtype: string
 
     '''
     activity_stream = package_activity_list(context, data_dict)
     return _activity_list_to_html(context, activity_stream)
 
 def group_activity_list_html(context, data_dict):
-    '''Return an HTML rendering of a group\'s public activity stream.
+    '''Return an HTML rendering of a group's activity stream.
 
     The activity stream is rendered as a snippet of HTML meant to be included
-    in an HTML page.
+    in an HTML page, i.e. it doesn't have any HTML header or footer.
+
+    :param id: The id or name of the group.
+    :type id: string
+    :returns: The activity stream as HTML.
+    :rtype: string
 
     '''
     activity_stream = group_activity_list(context, data_dict)
@@ -1372,13 +1387,9 @@ def recently_changed_packages_activity_list_html(context, data_dict):
     or updated packages.
 
     The activity stream is rendered as a snippet of HTML meant to be included
-    in an HTML page.
+    in an HTML page, i.e. it doesn't have any HTML header or footer.
 
-    :param context: The current Pylons context.
-    :type context: dictionary
-    :param data_dict: The data dict.
-    :type data_dict: dicttionary
-    :returns: The recently changed activity list in HTML format.
+    :returns: The activity stream as HTML.
     :rtype: string
 
     '''
diff --git a/doc/api-ref.rst b/doc/api-ref.rst
index 5c8a474..4ecabf3 100644
--- a/doc/api-ref.rst
+++ b/doc/api-ref.rst
@@ -5,5 +5,9 @@
 CKAN API Reference
 ==================
 
+TODO: Explain how to call API functions. In the source code, all of these functions take two params context and data_dict, but the params documented in the docstrings are actually the keys that should be in the data_dict. When you post a json dict to an API endpoint, the json dict becomes the data_dict. Give an example with curl.
+
+Also explain how the returns values of the functions end up in the json dict that is returned.
+
 .. automodule:: ckan.logic.action.get
    :members:


================================================================