Merge branch 'feature-2345-action-api-autodocs'

ckan/logic/action/get.py

@@ -982,21 +982,93 @@ def user_autocomplete(context, data_dict):
 
 def package_search(context, data_dict):
     '''
+    Searches for packages satisfying a given search criteria.
 
-    :param q:
-    :type q:
-    :param fields:
-    :type fields:
-    :param facet_by:
-    :type facet_by:
-    :param limit:
-    :type limit:
-    :param offset:
-    :type offset:
+    This action accepts solr search query parameters (details below), and
+    returns a dictionary of results, including dictized datasets that match
+    the search criteria, a search count and also facet information.
 
-    :returns:
-    :rtype:
+    **Solr Parameters:**
+
+    For more in depth treatment of each paramter, please read the `Solr
+    Documentation <http://wiki.apache.org/solr/CommonQueryParameters>`_.
 
+    This action accepts a *subset* of solr's search query parameters:
+
+    :param q: the solr query.  Optional.  Default: `"*:*"`
+    :type q: string
+    :param fq: any filter queries to apply.  Note: `+site_id:{ckan_site_id}`
+        is added to this string prior to the query being executed.
+    :type fq: string
+    :param rows: the number of matching rows to return.
+    :type rows: int
+    :param sort: sorting of the search results.  Optional.  Default:
+        "score desc, name asc".  As per the solr documentation, this is a
+        comma-separated string of field names and sort-orderings.
+    :type sort: string
+    :param start: the offset in the complete result for where the set of
+        returned datasets should begin.
+    :type start: int
+    :param qf: the dismax query fields to search within, including boosts.  See
+        the `Solr Dismax Documentation 
+        <http://wiki.apache.org/solr/DisMaxQParserPlugin#qf_.28Query_Fields.29>`_
+        for further details.
+    :type qf: string
+    :param facet: whether to enable faceted results.  Default: "true".
+    :type facet: string
+    :param facet.mincount: the minimum counts for facet fields should be
+        included in the results.
+    :type facet.mincount: int
+    :param facet.limit: the maximum number of constraint counts that should be
+        returned for the facet fields. A negative value means unlimited
+    :type facet.limit: int
+    :param facet.field: the fields to facet upon.  Default empty.  If empty,
+        then the returned facet information is empty.
+    :type facet.field: list of strings
+
+    **Results:**
+
+    The result of this action is a dict with the following keys:
+
+    :rtype: A dictionary with the following keys
+    :param count: the number of results found.  Note, this is the total number
+        of results found, not the total number of results returned (which is
+        affected by limit and row parameters used in the input).
+    :type count: int
+    :param results: ordered list of datasets matching the query, where the
+        ordering defined by the sort parameter used in the query.
+    :type results: list of dictized datasets.
+    :param search_facets: aggregated information about facet counts.  The outer
+        dict is keyed by the facet field name (as used in the search query).
+        Each entry of the outer dict is itself a dict, with a "title" key, and
+        an "items" key.  The "items" key's value is a list of dicts, each with
+        "count", "display_name" and "name" entries.  The display_name is a
+        form of the name that can be used in titles.
+    :type search_facets: nested dict of dicts.
+
+    An example result: ::
+
+     {'count': 2,
+      'results': [ { <snip> }, { <snip> }],
+      'search_facets': {u'tags': {'items': [{'count': 1,
+                                             'display_name': u'tolstoy',
+                                             'name': u'tolstoy'},
+                                            {'count': 2,
+                                             'display_name': u'russian',
+                                             'name': u'russian'}
+                                           ]
+                                 }
+                       }
+     }
+
+    **Limitations:**
+
+    The full solr query language is not exposed, including.
+
+    fl
+        The parameter that controls which fields are returned in the solr
+        query cannot be changed.  CKAN always returns the matched datasets as
+        dictionary objects.
     '''
     model = context['model']
     session = context['session']

doc/apiv3.rst

@@ -57,25 +57,8 @@ Examples::
  curl http://test.ckan.net/api/action/package_list -d '{}'
  curl http://test.ckan.net/api/action/package_show -d '{"id": "fd788e57-dce4-481c-832d-497235bf9f78"}'
 
-Actions
-=======
-
-.. automodule:: ckan.logic.action.get
-   :members:
-
-.. automodule:: ckan.logic.action.create
-   :members:
-
-.. automodule:: ckan.logic.action.update
-   :members:
-
-.. automodule:: ckan.logic.action.delete
-   :members:
-
-In case of doubt, refer to the code of the logic actions, which is found in the CKAN source in the ``ckan/logic/action`` directory.
-
 GET-able Actions
-----------------
+................
 
 Actions defined in get.py can also be accessed with a GET request **in
 addition** to the POST method described just above.
@@ -112,6 +95,23 @@ consequence of this, currently the *resource_search*, *tag_search* and
 Also, it is worth bearing this limitation in mind when creating your own
 actions via the `IActions` interface.
 
+Actions
+=======
+
+.. automodule:: ckan.logic.action.get
+   :members:
+
+.. automodule:: ckan.logic.action.create
+   :members:
+
+.. automodule:: ckan.logic.action.update
+   :members:
+
+.. automodule:: ckan.logic.action.delete
+   :members:
+
+In case of doubt, refer to the code of the logic actions, which is found in the CKAN source in the ``ckan/logic/action`` directory.
+
 Responses
 =========