[#1022] Fix cross-references in API docstrings

Use :py:func:, :py:class: etc to do proper hyperlinked cross-references.

Also a few other minor docstrings formatting fixes.

ckan/logic/action/create.py

@@ -45,7 +45,8 @@ def package_create(context, data_dict):
     for the new dataset, you must also be authorized to edit these groups.
 
     Plugins may change the parameters of this function depending on the value
-    of the ``type`` parameter, see the ``IDatasetForm`` plugin interface.
+    of the ``type`` parameter, see the
+    :py:class:`~ckan.plugins.interfaces.IDatasetForm` plugin interface.
 
     :param name: the name of the new dataset, must be between 2 and 100
         characters long and contain only lowercase alphanumeric characters,
@@ -63,8 +64,9 @@ def package_create(context, data_dict):
     :param maintainer_email: the email address of the dataset's maintainer
         (optional)
     :type maintainer_email: string
-    :param license_id: the id of the dataset's license, see ``license_list()``
-        for available values (optional)
+    :param license_id: the id of the dataset's license, see
+        :py:func:`~ckan.logic.action.get.license_list` for available values
+        (optional)
     :type license_id: license id string
     :param notes: a description of the dataset (optional)
     :type notes: string
@@ -78,41 +80,45 @@ def package_create(context, data_dict):
         authorized to change the state of the dataset (optional, default:
         ``'active'``)
     :type state: string
-    :param type: the type of the dataset (optional), ``IDatasetForm`` plugins
+    :param type: the type of the dataset (optional),
+        :py:class:`~ckan.plugins.interfaces.IDatasetForm` plugins
         associate themselves with different dataset types and provide custom
         dataset handling behaviour for these types
     :type type: string
-    :param resources: the dataset's resources, see ``resource_create()``
-        for the format of resource dictionaries (optional)
+    :param resources: the dataset's resources, see
+        :py:func:`resource_create` for the format of resource dictionaries
+        (optional)
     :type resources: list of resource dictionaries
-    :param tags: the dataset's tags, see ``tag_create()`` for the format
+    :param tags: the dataset's tags, see :py:func:`tag_create` for the format
         of tag dictionaries (optional)
     :type tags: list of tag dictionaries
     :param extras: the dataset's extras (optional), extras are arbitrary
         (key: value) metadata items that can be added to datasets, each extra
         dictionary should have keys ``'key'`` (a string), ``'value'`` (a
         string)
     :type extras: list of dataset extra dictionaries
-    :param relationships_as_object: see ``package_relationship_create()`` for
-        the format of relationship dictionaries (optional)
+    :param relationships_as_object: see :py:func:`package_relationship_create`
+        for the format of relationship dictionaries (optional)
     :type relationships_as_object: list of relationship dictionaries
-    :param relationships_as_subject: see ``package_relationship_create()`` for
-        the format of relationship dictionaries (optional)
+    :param relationships_as_subject: see :py:func:`package_relationship_create`
+        for the format of relationship dictionaries (optional)
     :type relationships_as_subject: list of relationship dictionaries
     :param groups: the groups to which the dataset belongs (optional), each
         group dictionary should have one or more of the following keys which
         identify an existing group:
         ``'id'`` (the id of the group, string), ``'name'`` (the name of the
         group, string), ``'title'`` (the title of the group, string), to see
-        which groups exist call ``group_list()``
+        which groups exist call :py:func:`~ckan.logic.action.get.group_list`
     :type groups: list of dictionaries
     :param owner_org: the id of the dataset's owning organization, see
-        ``organization_list()`` or ``organization_list_for_user`` for
+        :py:func:`~ckan.logic.action.get.organization_list` or
+        :py:func:`~ckan.logic.action.get.organization_list_for_user` for
         available values (optional)
     :type owner_org: string
 
-    :returns: the newly created dataset (unless 'return_id_only' is set to True
-              in the context, in which case just the dataset id will be returned)
+    :returns: the newly created dataset (unless ``'return_id_only'`` is set to
+              ``True`` in the context, in which case just the dataset id will
+              be returned)
     :rtype: dictionary
 
     '''
@@ -617,7 +623,8 @@ def group_create(context, data_dict):
     You must be authorized to create groups.
 
     Plugins may change the parameters of this function depending on the value
-    of the ``type`` parameter, see the ``IGroupForm`` plugin interface.
+    of the ``type`` parameter, see the
+    :py:class:`~ckan.plugins.interfaces.IGroupForm` plugin interface.
 
     :param name: the name of the group, a string between 2 and 100 characters
         long, containing only lowercase alphanumeric characters, ``-`` and
@@ -632,7 +639,8 @@ def group_create(context, data_dict):
     :param image_url: the URL to an image to be displayed on the group's page
         (optional)
     :type image_url: string
-    :param type: the type of the group (optional), ``IGroupForm`` plugins
+    :param type: the type of the group (optional),
+        :py:class:`~ckan.plugins.interfaces.IGroupForm` plugins
         associate themselves with different group types and provide custom
         group handling behaviour for these types
         Cannot be 'organization'
@@ -683,7 +691,8 @@ def organization_create(context, data_dict):
     You must be authorized to create organizations.
 
     Plugins may change the parameters of this function depending on the value
-    of the ``type`` parameter, see the ``IGroupForm`` plugin interface.
+    of the ``type`` parameter, see the
+    :py:class:`~ckan.plugins.interfaces.IGroupForm` plugin interface.
 
     :param name: the name of the organization, a string between 2 and 100 characters
         long, containing only lowercase alphanumeric characters, ``-`` and
@@ -962,7 +971,7 @@ def vocabulary_create(context, data_dict):
     :param name: the name of the new vocabulary, e.g. ``'Genre'``
     :type name: string
     :param tags: the new tags to add to the new vocabulary, for the format of
-        tag dictionaries see ``tag_create()``
+        tag dictionaries see :py:func:`tag_create`
     :type tags: list of tag dictionaries
 
     :returns: the newly-created vocabulary
@@ -1001,8 +1010,7 @@ def activity_create(context, activity_dict, **kw):
         ``'my_dataset'``
     :param activity_type: the type of the activity, this must be an activity
         type that CKAN knows how to render, e.g. ``'new package'``,
-        ``'changed user'``, ``'deleted group'`` etc. (for a full list see
-        ``activity_renderers`` in ``ckan/logic/action/get.py``
+        ``'changed user'``, ``'deleted group'`` etc.
     :type activity_type: string
     :param data: any additional data about the activity
     :type data: dictionary
@@ -1066,7 +1074,8 @@ def tag_create(context, data_dict):
 
     You can only use this function to create tags that belong to a vocabulary,
     not to create free tags. (To create a new free tag simply add the tag to
-    a package, e.g. using the ``package_update`` function.)
+    a package, e.g. using the
+    :py:func:`~ckan.logic.action.update.package_update` function.)
 
     :param name: the name for the new tag, a string between 2 and 100
         characters long containing only alphanumeric characters and ``-``,

ckan/logic/action/get.py

@@ -447,10 +447,10 @@ def group_list_authz(context, data_dict):
       (optional, default: ``False``)
     :type available_only: boolean
 
-    :param am_member: if True return only the groups the logged-in user is a
-      member of, otherwise return all groups that the user is authorized to
+    :param am_member: if ``True`` return only the groups the logged-in user is
+      a member of, otherwise return all groups that the user is authorized to
       edit (for example, sysadmin users are authorized to edit all groups)
-      (optional, default: False)
+      (optional, default: ``False``)
     :type am-member: boolean
 
     :returns: list of dictized groups that the user is authorized to edit
@@ -742,8 +742,8 @@ def package_relationships_list(context, data_dict):
     :param id2: the id or name of the second package
     :type id: string
     :param rel: relationship as string see
-        :func:`ckan.logic.action.create.package_relationship_create()` for the
-        relationship types (optional)
+        :py:func:`~ckan.logic.action.create.package_relationship_create` for
+        the relationship types (optional)
 
     :rtype: list of dictionaries
 
@@ -1330,13 +1330,13 @@ def package_search(context, data_dict):
     This action accepts a *subset* of solr's search query parameters:
 
 
-    :param q: the solr query.  Optional.  Default: `"*:*"`
+    :param q: the solr query.  Optional.  Default: ``"*:*"``
     :type q: string
-    :param fq: any filter queries to apply.  Note: `+site_id:{ckan_site_id}`
+    :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 sort: sorting of the search results.  Optional.  Default:
-        'relevance asc, metadata_modified desc'.  As per the solr
+        ``'relevance asc, metadata_modified desc'``.  As per the solr
         documentation, this is a comma-separated string of field names and
         sort-orderings.
     :type sort: string
@@ -1345,7 +1345,7 @@ def package_search(context, data_dict):
     :param start: the offset in the complete result for where the set of
         returned datasets should begin.
     :type start: int
-    :param facet: whether to enable faceted results.  Default: "true".
+    :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.
@@ -1616,7 +1616,7 @@ def resource_search(context, data_dict):
     queries (rather than ValidationErrors).
 
     :param query: The search criteria.  See above for description.
-    :type query: string or list of strings of the form "{field}:{term1}"
+    :type query: string or list of strings of the form ``{field}:{term1}``
     :param fields: Deprecated
     :type fields: dict of fields to search terms.
     :param order_by: A field on the Resource model that orders the results.
@@ -2664,11 +2664,12 @@ def followee_list(context, data_dict):
         (optional)
     :type q: string
 
-    :rtype: list of dictionaries, each with keys 'type' (e.g. 'user',
-        'dataset' or 'group'), 'display_name' (e.g. a user's display name,
-        or a package's title) and 'dict' (e.g. a dict representing the
-        followed user, package or group, the same as the dict that would be
-        returned by user_show, package_show or group_show)
+    :rtype: list of dictionaries, each with keys ``'type'`` (e.g. ``'user'``,
+        ``'dataset'`` or ``'group'``), ``'display_name'`` (e.g. a user's
+        display name, or a package's title) and ``'dict'`` (e.g. a dict
+        representing the followed user, package or group, the same as the dict
+        that would be returned by :py:func:`user_show`,
+        :py:func:`package_show` or :py:func:`group_show`)
 
     '''
     _check_access('followee_list', context, data_dict)
@@ -2824,7 +2825,7 @@ def dashboard_activity_list(context, data_dict):
     :type offset: int
     :param limit: the maximum number of activities to return
         (optional, default: 31, the default value is configurable via the
-        ``ckan.activity_list_limit`` setting)
+        :ref:`ckan.activity_list_limit` setting)
 
     :rtype: list of activity dictionaries
 
@@ -2952,12 +2953,12 @@ def _unpick_search(sort, allowed_fields=None, total=None):
 def member_roles_list(context, data_dict):
     '''Return the possible roles for members of groups and organizations.
 
-    :param group_type: the group type, either "group" or "organization"
-        (optional, default "organization")
+    :param group_type: the group type, either ``"group"`` or ``"organization"``
+        (optional, default ``"organization"``)
     :type id: string
-    :returns: a list of dictionaries each with two keys: "text" (the display
-        name of the role, e.g. "Admin") and "value" (the internal name of the
-        role, e.g. "admin")
+    :returns: a list of dictionaries each with two keys: ``"text"`` (the
+        display name of the role, e.g. ``"Admin"``) and ``"value"`` (the
+        internal name of the role, e.g. ``"admin"``)
     :rtype: list of dictionaries
 
     '''

ckan/logic/action/update.py

@@ -67,7 +67,9 @@ def _make_latest_rev_active(context, q):
         context['latest_revision'] = latest_rev.revision_id
 
 def make_latest_pending_package_active(context, data_dict):
-    '''TODO: What does this function do?
+    '''
+
+    .. todo:: What does this function do?
 
     You must be authorized to update the dataset.
 
@@ -120,7 +122,8 @@ def related_update(context, data_dict):
 
     You must be the owner of a related item to update it.
 
-    For further parameters see ``related_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.related_create`.
 
     :param id: the id of the related item to update
     :type id: string
@@ -187,7 +190,8 @@ def resource_update(context, data_dict):
     To update a resource you must be authorized to update the dataset that the
     resource belongs to.
 
-    For further parameters see ``resource_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.resource_create`.
 
     :param id: the id of the resource to update
     :type id: string
@@ -245,16 +249,17 @@ def package_update(context, data_dict):
     to.
 
     Plugins may change the parameters of this function depending on the value
-    of the dataset's ``type`` attribute, see the ``IDatasetForm`` plugin
-    interface.
+    of the dataset's ``type`` attribute, see the
+    :py:class:`~ckan.plugins.interfaces.IDatasetForm` plugin interface.
 
-    For further parameters see ``package_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.package_create`.
 
     :param id: the name or id of the dataset to update
     :type id: string
 
-    :returns: the updated dataset (if 'return_package_dict' is True in the
-              context, which is the default. Otherwise returns just the
+    :returns: the updated dataset (if ``'return_package_dict'`` is ``True`` in
+              the context, which is the default. Otherwise returns just the
               dataset id)
     :rtype: dictionary
 
@@ -598,9 +603,11 @@ def group_update(context, data_dict):
     You must be authorized to edit the group.
 
     Plugins may change the parameters of this function depending on the value
-    of the group's ``type`` attribute, see the ``IGroupForm`` plugin interface.
+    of the group's ``type`` attribute, see the
+    :py:class:`~ckan.plugins.interfaces.IGroupForm` plugin interface.
 
-    For further parameters see ``group_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.group_create`.
 
     :param id: the name or id of the group to update
     :type id: string
@@ -616,7 +623,8 @@ def organization_update(context, data_dict):
 
     You must be authorized to edit the organization.
 
-    For further parameters see ``organization_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.organization_create`.
 
     :param id: the name or id of the organization to update
     :type id: string
@@ -633,7 +641,8 @@ def user_update(context, data_dict):
     Normal users can only update their own user accounts. Sysadmins can update
     any user account.
 
-    For further parameters see ``user_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.user_create`.
 
     :param id: the name or id of the user to update
     :type id: string
@@ -740,7 +749,8 @@ def task_status_update_many(context, data_dict):
     '''Update many task statuses at once.
 
     :param data: the task_status dictionaries to update, for the format of task
-        status dictionaries see ``task_status_update()``
+        status dictionaries see 
+        :py:func:`~task_status_update`
     :type data: list of dictionaries
 
     :returns: the updated task statuses
@@ -814,7 +824,7 @@ def term_translation_update_many(context, data_dict):
 
     :param data: the term translation dictionaries to create or update,
         for the format of term translation dictionaries see
-        ``term_translation_update()``
+        :py:func:`~term_translation_update`
     :type data: list of dictionaries
 
     :returns: a dictionary with key ``'success'`` whose value is a string
@@ -898,7 +908,8 @@ def vocabulary_update(context, data_dict):
 
     You must be a sysadmin to update vocabularies.
 
-    For further parameters see ``vocabulary_create()``.
+    For further parameters see
+    :py:func:`~ckan.logic.action.create.vocabulary_create`.
 
     :param id: the id of the vocabulary to update
     :type id: string
@@ -1023,7 +1034,7 @@ def user_role_bulk_update(context, data_dict):
     You must be authorized to update the domain object.
 
     :param user_roles: the updated user roles, for the format of user role
-        dictionaries see ``user_role_update()``
+        dictionaries see :py:func:`~user_role_update`
     :type user_roles: list of dictionaries
 
     :returns: the updated roles of all users and authorization groups for the
@@ -1052,7 +1063,8 @@ def user_role_bulk_update(context, data_dict):
 def dashboard_mark_activities_old(context, data_dict):
     '''Mark all the authorized user's new dashboard activities as old.
 
-    This will reset dashboard_new_activities_count to 0.
+    This will reset
+    :py:func:`~ckan.logic.action.get.dashboard_new_activities_count` to 0.
 
     '''
     _check_access('dashboard_mark_activities_old', context,