Merge branch 'develop'

Author: pombredanne

NOTICE

@@ -1,4 +1,4 @@
- Copyright (c) 2013-2014 nexB Inc. http://www.nexb.com/ - All rights reserved.
+ Copyright (c) 2013-2015 nexB Inc. http://www.nexb.com/ - All rights reserved.
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

README.rst

@@ -122,9 +122,6 @@ information will be saved to the CSV file named "thirdparty_about.csv".
                             1 - Overwrites the current ABOUT field value if existed
                             2 - Keep the current field value and only add the "new" field and field value
                             3 - Replace the ABOUT file with the current generation
-    
-      --all_in_one          Generate all the ABOUT files in the [output_path] without
-                            any project structure
 
       --copy_files=COPY_FILES
                             Copy the '*_file' from the project to the generated location

USAGE USAGE.rstUSAGE renamed to USAGE.rst

@@ -1,17 +1,19 @@
-========
 about.py
 ========
 
-------
-Syntax
-------
+**Syntax**
+
+::
+
+    about.py [options] input_path output_path
 
-    Usage: about.py [options] input_path output_path
+    - Input can be a file or directory.
+    - Output must be a file with a .csv extension.
 
-    Input can be a file or directory.
-    Output must be a file with a .csv extension.
+**Options:**
+
+::
 
-    Options:
       -h, --help            Display help
       --version             Display current version, license notice, and copyright notice
       --overwrite           Overwrites the output file if it exists
@@ -21,38 +23,38 @@ Syntax
                             1 - Print error messages
                             2 - Print error and warning messages
 
--------
 Purpose
 -------
+Extract information from the .ABOUT files and save it to the CSV file.
 
-    Extract information from the .ABOUT files and save it to the CSV file.
-
--------
 Options
 -------
 
+::
+
     --overwrite
  
         Overwrite the extracted data from .ABOUT files to the output location
 
-            $ python about.py --overwrite <input path> <output path>
+    $ python about.py --overwrite <input path> <output path>
 
 
-===========
 genabout.py
 ===========
 
-------
-Syntax
-------
+**Syntax**
+
+::
+
+    genabout.py [options] input_path output_path
 
-    Usage: genabout.py [options] input_path output_path
+    - Input must be a CSV file
+    - Output must be a directory location where the ABOUT files should be generated
 
-        Input must be a CSV file
-        Output must be a directory location where the ABOUT files should be generated
+**Options:**
 
+::
 
-    Options:
       -h, --help            Display help
       --version             Display current version, license notice, and copyright notice
       --verbosity=VERBOSITY
@@ -67,9 +69,6 @@ Syntax
                             2 - Keep the current field value and only add the "new" field and field value
                             3 - Replace the ABOUT file with the current generation
 
-      --all_in_one          Generate all the ABOUT files in the [output_path] without
-                            any project structure
-
       --copy_files=COPY_FILES
                             Copy the '*_file' from the project to the generated location
                             Project path - Project path
@@ -91,28 +90,21 @@ Syntax
                             Example syntax:
                             genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key'
 
--------
 Purpose
 -------
+Generate ABOUT files from the input CSV file to output location.
 
-    Generate ABOUT files from the input CSV file to output location
-
--------
 Options
 -------
 
+::
+
     --action=ACTION
 
         Handle different behaviors if ABOUT files already existed.
         For instance, replace the ABOUT files with the current generation
 
-            $ python genabout.py --action=3 <input path> <output path>
-
-    --all_in_one
-
-        Generate all the ABOUT files to the output location without any project structure
-
-            $ python genabout.py --all_in_one <input path> <output path>
+    $ python genabout.py --action=3 <input path> <output path>
 
     --copy_files
 
@@ -127,7 +119,7 @@ Options
         'license_text_file' and 'notice_text_file' from
         /home/project/ to /home/about/
 
-            $ python genabout.py --copy_files=/home/project/ <input path> /home/about/
+    $ python genabout.py --copy_files=/home/project/ <input path> /home/about/
 
     --license_text_location
 
@@ -139,34 +131,43 @@ Options
         /home/license/apache2.LICENSE
         /home/license/jquery.js.LICENSE
 
-            $ python genabout.py --license_text_location=/home/licenses/ <input path> <output path>
+    $ python genabout.py --license_text_location=/home/licenses/ <input path> <output path>
 
     --mapping
 
         This tool needs the input CSV to have the required and/or optional keys to work.
-        By understanding the user's input may not have the same keys name as the tool use,
-        there are two ways the users can do.
-        1. Change the keys name directly in the input manually.
-        2. Use the '--mapping' option to configure the keys mapping.
-
-        When the '--mapping' is set, this tool will look into the 'MAPPING.CONFIG'
-        and do the keys mapping.
-
-        For instance, assuming the context of the MAPPING.CONFIG is the following:
+        Since the user input may not have the same column key names used by the tool,
+        there are two ways to reconcile that:
+        1. Change the key names directly in the input manually to match the field names
+        supported by the AboutCode specification.
+        Note: genabout.py looks for an about_file field and uses it to derive the mandatory
+        output field about_resource.
+        2. Use the '--mapping' option to configure the key mapping. This method provides the
+        most flexiblity and control. 
+        When the '--mapping' option is set, the tool will look into the 'MAPPING.CONFIG'
+        file to determine key mapping.
+        
+        The format of each text line in the MAPPING.CONFIG file is as follows:
+            {{about_file_target_field_name}}: {{input_csv_file_field_name}}
+
+        For instance, assume that MAPPING.CONFIG contains the following:
             about_resource: file_name
             about_file: Resource
             name: Component
             version: file_version
 
-        This tool will look into the input CSV and try to find the column key named
-        'file_name' and configure to map with the 'about_resource' key that this
-        tool use. The 'Resource' will then configure to map with 'about_file' and
+        The tool will look into the input CSV and try to find the column key named
+        'file_name' and configure to map with the 'about_resource' key that the
+        tool uses. The 'Resource' will then configure to map with 'about_file' and
         so on.
 
-        In another word, users do not need to modify the keys name of the
-        input manually but let the 'MAPPING.CONFIG' to do the keys mapping.
+        In another word, you do not need to modify the key names of the
+        input manually, but rather use the MAPPING.CONFIG to do the key mapping.
+        
+        Another advantage of using the MAPPING.CONFIG is the ability to specify 
+        any field names that are important to you, including custom fields.
 
-            $ python genabout.py --mapping <input path> <output path>
+    $ python genabout.py --mapping <input path> <output path>
 
     --extract_license
 
@@ -181,68 +182,71 @@ Options
                         yourself in the API.
         (Please contact us to get the api_* value to use this feature)
 
-            genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key' <input path> <output path>
+    $ python genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key' <input path> <output path>
 
 
-============
 genattrib.py
 ============
 
-------
-Syntax
-------
+**Syntax**
 
-    Usage: genattrib.py [options] input_path output_path component_list
-    
-        Input can be a file or directory.
-        Output of rendered template must be a file (e.g. .html).
-        Component List must be a .csv file which has at least an "about_file" column.
-    
-    
-    Options:
-      -h, --help            Display help
-      -v, --version         Display current version, license notice, and copyright notice
-      --overwrite           Overwrites the output file if it exists
-      --verbosity=VERBOSITY
-                            Print more or fewer verbose messages while processing ABOUT files
-                            0 - Do not print any warning or error messages, just a total count (default)
-                            1 - Print error messages
-                            2 - Print error and warning messages
+::
 
-      --template_location=TEMPLATE_LOCATION
-                            Use the custom template for the Attribution Generation
+    genattrib.py [options] input_path output_path component_list
 
-      --mapping             Configure the mapping key from the MAPPING.CONFIG
+    - Input can be a file or directory.
+    - Output of rendered template must be a file (e.g. .html).
+    - Component List must be a .csv file which has at least an "about_file" column.
+
+**Options:**
+
+::
+
+    -h, --help          Display help
+    --version           Display current version, license notice, and copyright notice
+    --overwrite         Overwrites the output file if it exists
+    --verbosity=VERBOSITY
+                        Print more or fewer verbose messages while processing ABOUT files
+                        0 - Do not print any warning or error messages, just a total count (default)
+                        1 - Print error messages
+                        2 - Print error and warning messages
+    --template_location=TEMPLATE_LOCATION
+                        Use the custom template for the Attribution Generation
+    --mapping           Configure the mapping key from the MAPPING.CONFIG
 
--------
 Purpose
 -------
+Generate an Attribution HTML file which contains the license information from
+the 'component_list' along with the license text.
+
+This tool will look at the components in the 'component_list' and find the
+corresponding .ABOUT files in the 'input_path' and generate the output in
+the 'output_path'. Therefore, please make sure there are .ABOUT files under
+the 'input_path'.
 
-    Generate an Attribution HTML file which contains the license information from
-    the 'component_list' along with the license text.
+Assuming the follow:
 
-    This tool will look at the components in the 'component_list' and find the
-    corresponding .ABOUT files in the 'input_path' and generate the output in
-    the 'output_path'. Therefore, please make sure there are .ABOUT files under
-    the 'input_path'.
+::
 
-    Assuming the follow:
-    '/home/about_files/' contains all the ABOUT files from the component_list
+    '/home/about_files/'** contains all the ABOUT files from the component_list
     '/home/attribution/attribution.html' is the user's output path
     '/home/project/component_list.csv' is the component list that user want to be generated
 
-        $ python genattrib.py /home/about_files/ /home/attribution/attribution.html /home/project/component_list.csv
+::
+
+    $ python genattrib.py /home/about_files/ /home/attribution/attribution.html /home/project/component_list.csv
 
--------
 Options
 -------
 
-    --template_location
+::
 
+    --template_location
+    
         This option allows you to use your own template for Attribution Generation.
         For instance, if the custom template you want to use is located at:
         /home/custom_template/template.html
 
-            $ python genattrib.py --template_location=/home/custom_template/template.html input_path output_path component_list
+    $ python genattrib.py --template_location=/home/custom_template/template.html input_path output_path component_list
 
 

about.ABOUT

@@ -1,7 +1,7 @@
 about_resource: .
 
 name: AboutCode
-version: 1.0.2
+version: 2.0.0
 
 
 owner: nexB Inc.
@@ -21,6 +21,6 @@ description: AboutCode is a tool to process ABOUT files. An ABOUT file
 dje_license: apache-2.0
 license_text_file: apache-2.0.LICENSE
 license_spdx: Apache-2.0
-copyright: Copyright (c) 2013-2014 nexB Inc.
+copyright: Copyright (c) 2013-2015 nexB Inc.
 
 notice_file: NOTICE