[#847] example_theme plugin_v7 tweaks

Comments, etc.

ckanext/example_theme/v7/plugin.py

@@ -4,14 +4,20 @@
 import ckan.plugins.toolkit as toolkit
 
 
-def example_theme_dataset_of_the_day():
+def dataset_of_the_day():
     '''Return the dataset of the day.
 
     '''
+    # Get a list of the names of all of the site's datasets.
     dataset_names = toolkit.get_action('package_list')(data_dict={})
+
+    # Choose one dataset name at random.
     dataset_name = random.choice(dataset_names)
+
+    # Get the full dictionary object for the chosen dataset.
     dataset = toolkit.get_action('package_show')(
         data_dict={'id': dataset_name})
+
     return dataset
 
 
@@ -20,6 +26,8 @@ class ExampleThemePlugin(plugins.SingletonPlugin):
 
     '''
     plugins.implements(plugins.IConfigurer)
+
+    # Declare that this plugin will implement ITemplateHelpers.
     plugins.implements(plugins.ITemplateHelpers)
 
     def update_config(self, config):
@@ -29,6 +37,11 @@ def update_config(self, config):
         toolkit.add_template_directory(config, 'templates')
 
     def get_helpers(self):
-
-        return {'example_theme_dataset_of_the_day':
-                example_theme_dataset_of_the_day}
+        '''Register the dataset_of_the_day() function above as a template
+        helper function.
+
+        '''
+        # Template helper function names should begin with the name of the
+        # extension they belong to, to avoid clashing with functions from
+        # other extensions.
+        return {'example_theme_dataset_of_the_day': dataset_of_the_day}