Update documentation around resource and QuickCharts generation

Author: Mike

doc/main.md

@@ -27,7 +27,10 @@ upload your datasets to HDX.
         -   [Tags](#tags)
         -   [Maintainer](#maintainer)
         -   [Organization](#organization)
+        -   [Resource Generation](#resource-generation)
+        -   [QuickCharts Generation](#quickcharts-generation)
     -   [Resource Specific Operations](#resource-specific-operations)
+    -   [Showcase Management](#showcase-management)
     -   [User Management](#user-management)
     -   [Organization Management](#organization-management)
     -   [Vocabulary Management](#vocabulary-management)
@@ -48,6 +51,8 @@ The library has detailed API documentation which can be found in the menu at the
 
 
 ## Breaking Changes
+From 6.0.0, generate_resource_view is renamed to generate_quickcharts
+
 From 5.9.9, get_location_iso3s returns uppercase codes instead of lowercase
 
 From 5.9.8, get_date_of_dataset has become get_reference_period, 
@@ -738,6 +743,132 @@ If you want to set the organization, you do it like this:
 ORGANIZATION is either a string id, dictionary or an Organization
 object.
 
+### Resource generation
+
+There are a range of helpful functions to generate resources. In the following
+examples, RESOURCE DATA takes the form {"name": NAME, "description": 
+DESCRIPTION} and ENCODING is a file encoding like "utf-8".  
+
+A resource can be generated from ROWS which is a list of list, tuple or 
+dictionary. HEADERS is either a row number (rows start counting at 1), or the 
+actual headers defined as a list of strings. If not set, all rows will be 
+treated as containing values:
+
+    dataset.generate_resource_from_rows("FOLDER", "FILENAME", ROWS, 
+                                        RESOURCE DATA, HEADERS, "ENCODING")
+
+A resource for the purpose of driving QuickCharts can be generated by taking 
+ROWS, a list of dictionaries, and producing a cut down subset from it. HXLTAGS 
+are added as the second row after the header. The reduction in rows is 
+performed by only outputting the rows where COLUMN_NAME has a value in 
+QC_IDENTIFIERS. Optionally the columns that are output can be limited by 
+specifying them in HEADERS. 
+
+    dataset.generate_qc_resource_from_rows("FOLDER", "FILENAME", ROWS,
+    RESOURCE DATA, HXLTAGS, "COLUMN_NAME", QC_IDENTIFIERS, HEADERS, "ENCODING")
+
+Building on these basic resource generation methods, there are more powerful 
+ones `generate_resource_from_iterator` and `download_and_generate_resource`. 
+
+A resource can be generated from a given list or tuple: HEADERS and an ITERATOR 
+which can return rows in list, tuple or dictionary form. A mapping from headers 
+to HXL hashtags, HXLTAGS, must be provided along with the FOLDER and FILENAME 
+where the file will be generated for upload to the filestore. The dataset 
+reference period can optionally be set by supplying DATECOL for looking up 
+dates or YEARCOL for looking up years. DATECOl and YEARCOL can be a column name
+or the index of a column. Note that any timezone information is ignored and UTC 
+is assumed. 
+
+Alternatively, DATE_FUNCTION can be supplied to handle any dates
+in a row. It should accept a row and should return None to ignore the row or a
+dictionary which can either be empty if there are no dates in the row or can be
+populated with keys startdate and/or enddate which are of type timezone-aware
+datetime. The lowest start date and highest end date are used to set the 
+reference period and are returned in the results dictionary in keys startdate 
+and enddate.
+
+    dataset.generate_resource_from_iterator(HEADERS, ITERATOR, HXLTAGS, 
+    "FOLDER", "FILENAME", RESOURCE_DATA, DATECOL or YEARCOL or DATE_FUNCTION,
+    QUICKCHARTS, "ENCODING")
+
+If desired, `generate_resource_from_iterator` can generate a separate 
+QuickCharts resource designed to be used in a time series QuickCharts bite 
+provided that the input has #indicator+code, #date and #indicator+value+num. 
+This is achieved by supplying the parameter QUICKCHARTS which activates various 
+QuickCharts related actions depending upon the keys given in the dictionary. 
+The returned dictionary will contain the QuickCharts resource in the key 
+qc_resource. If the keys: hashtag - the HXL hashtag to examine - and values -
+the 3 values to look for in that column - are supplied, then a list of booleans
+indicating which QuickCharts bites should be enabled will be returned in the 
+key bites_disabled in the returned dictionary. For the 3 values, if the key:
+numeric_hashtag is supplied then if that column for a given value contains no
+numbers, then the corresponding bite will be disabled. If the key: cutdown is
+given, if it is 1, then a separate cut down list is created containing only
+columns with HXL hashtags and rows with desired values (if hashtag and values
+are supplied) for the purpose of driving QuickCharts. It is returned in the key
+qcrows in the returned dictionary with the matching headers in qcheaders. If
+cutdown is 2, then a resource is created using the cut down list. If the key
+cutdownhashtags is supplied, then only the provided hashtags are used for
+cutting down otherwise the full list of HXL tags is used.
+
+The QuickCharts resource will be of form similar to below:
+
+    GHO (CODE),ENDYEAR,Numeric
+    #indicator+code,#date+year+end,#indicator+value+num
+    VIOLENCE_HOMICIDERATE,1994,123.4
+    MDG_0000000001,2015,123.4
+
+`download_and_generate_resource` builds on `generate_resource_from_iterator`.
+It uses an DOWNLOADER, an object of class `Download`, `Retrieve` or other class 
+that implements `BaseDownload` to download from URL. Additional arguments in 
+**KWARGS are passed to the `get_tabular_rows` method of the DOWNLOADER.
+
+Optionally, headers can be inserted at specific positions. This is achieved 
+using HEADER_INSERTIONS. If supplied, it is a list of tuples of the form 
+(position, header) to be inserted. A function, ROW_FUNCTION, is called for each 
+row. If supplied, it takes as arguments: headers (prior to any insertions) and 
+row (which will be in dict or list form depending upon the dict_rows argument) 
+and outputs a modified row. 
+
+The rest of the arguments are the same as for 
+`generate_resource_from_iterator`.
+
+    dataset.download_and_generate_resource(DOWNLOADER, "URL", HXLTAGS, 
+    "FOLDER", "FILENAME", RESOURCE_DATA, HEADER_INSERTIONS, ROW_FUNCTION,
+    DATECOL or YEARCOL or DATE_FUNCTION, QUICKCHARTS, **KWARGS)
+
+### QuickCharts Generation
+
+QuickCharts can be generated for datasets using the call below. RESOURCE is a
+a resource id or name, or resource metadata from a Resource object or a 
+dictionary, or the position of the resource in the dataset. It defaults to the
+position 0. PATH points to configuration which if not supplied, defaults to the 
+internal indicators resource view template. You can disable specific bites by 
+providing BITES_DISABLED, a list of 3 bools where True indicates a specific bite 
+is disabled and False indicates leave enabled. 
+
+    datasets.generate_quickcharts(RESOURCE, "PATH", BITES_DISABLED, INDICATORS,
+                                  FIND_REPLACE)
+
+The parameter INDICATORS is only for use with the built-in configuration and is
+a list with 3 dictionaries of form:
+
+        {"code": "MY_INDICATOR_CODE", "title": "MY_INDICATOR_TITLE",
+        "unit": "MY_INDICATOR_UNIT"}. 
+
+Optionally, the following defaults can be overridden in INDICATORS: 
+    
+    {"code_col": "#indicator+code", "value_col": "#indicator+value+num", 
+     "date_col": "#date+year", "date_format": "%Y", "aggregate_col": "null"}.
+
+The built-in configuration assumes data will be of form similar to below:
+
+    GHO (CODE),ENDYEAR,Numeric
+    #indicator+code,#date+year+end,#indicator+value+num
+    VIOLENCE_HOMICIDERATE,1994,123.4
+    MDG_0000000001,2015,123.4
+
+
 ## Resource Specific Operations
 
 You can download a resource using the **download** function eg.
@@ -759,8 +890,9 @@ There is a getter to read the value back:
     file_to_upload = resource.get_file_to_upload()
 
 ## Showcase Management
+
 The **Showcase** class enables you to manage showcases, creating, deleting and updating 
-(as for other HDX objects) according to  your permissions.
+(as for other HDX objects) according to your permissions.
 
 To see the list of datasets a showcase is in, you use the **get\_datasets** function eg.
 

setup.cfg

@@ -54,6 +54,3 @@ install_requires =
 [options.packages.find]
 where = src
 
-[bdist_wheel]
-universal = 1
-