From 5ad5b582a9f4126d9f485163c581d4d668dee861 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Tue, 10 Dec 2013 15:59:25 +0100 Subject: [PATCH] [#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 | 53 ++++++++++++++++++++++--------------- ckan/logic/action/get.py | 43 +++++++++++++++--------------- ckan/logic/action/update.py | 46 ++++++++++++++++++++------------ 3 files changed, 82 insertions(+), 60 deletions(-) diff --git a/ckan/logic/action/create.py b/ckan/logic/action/create.py index 1c8c0065ab6..9b99c4a42c5 100644 --- a/ckan/logic/action/create.py +++ b/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,14 +80,16 @@ 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 @@ -93,26 +97,28 @@ def package_create(context, data_dict): 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 ``-``, diff --git a/ckan/logic/action/get.py b/ckan/logic/action/get.py index 502b1bf92c9..239c7de4b9c 100644 --- a/ckan/logic/action/get.py +++ b/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 ''' diff --git a/ckan/logic/action/update.py b/ckan/logic/action/update.py index 920c68c4092..76dbf30b9ca 100644 --- a/ckan/logic/action/update.py +++ b/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,