Updated configure scripts and basic documentation.

Bump to 2.0.1

Author: pombredanne

.gitignore

@@ -9,6 +9,7 @@ lib64
 /Lib
 /Scripts
 /include
+/local
 
 # Installer logs
 pip-log.txt
@@ -29,4 +30,5 @@ nosetests.xml
 
 # PyCharm project
 .idea/
-/about_code_tool.egg_info
+
+/*.egg_info

README.rst

@@ -1,5 +1,5 @@
-ABOUT tool
-==========
+AboutCode tool
+==============
 
 .. image:: https://api.travis-ci.org/dejacode/about-code-tool.png?branch=develop
    :target: https://travis-ci.org/dejacode/about-code-tool
@@ -8,7 +8,7 @@ ABOUT tool
   :target: https://coveralls.io/r/dejacode/about-code-tool?branch=develop
 
 
-The ABOUT tool and ABOUT files provide a simple way to document the
+The AboutCode tool and ABOUT files provide a simple way to document the
 (origin and license) and other important or interesting information about
 third-party software components that you use in your project.
 
@@ -19,66 +19,108 @@ For more information on the ABOUT file format, visit http://www.dejacode.org
 There are many examples of ABOUT files (valid or invalid) in the testdata/
 directory of the whole repository.
 
-The current version of the ABOUT tool can read these ABOUT files so that you
+The current version of AboutCode can read these ABOUT files so that you
 can collect and validate the inventory of third-party components that you use.
 
-In future versions, this tool will be able to generate attribution notices and
-collect redistributable source code used in your project to help you comply
-with open source licenses requirements.
+This version of AboutCode follows the ABOUT specification version 1.0.0 at:
+https://github.com/dejacode/about-code-tool/blob/master/SPEC
 
-This version of the ABOUT tool follows the ABOUT specification version 0.8.1 at:
-http://www.dejacode.org/about_spec_v0.8.1.html
 
+License
+-------
+AboutCode is released under the Apache 2.0 license.
+See (of course) the about.ABOUT file for details.
 
-REQUIREMENTS
+
+Requirements
 ------------
-The ABOUT tool is tested with Python 2.6 or 2.7 on Linux, Mac and Windows.
-You will need to install a Python interpreter if you do not have one already
-installed.
+The AboutCode tool requires an installation Python 2.7 on Linux, Mac and Windows.
+You need to install Python if you do not have one already installed.
 
 On Linux and Mac, Python is typically pre-installed. To verify which
 version may be pre-installed, open a terminal and type::
 
     python --version
-    python2.6 --version
     python2.7 --version
 
-On Windows or Mac, you can download the latest Python 2.7.x here:
-    https://www.python.org/downloads/
+On Linux, Python2.7 may be available from your distro package manager.
+
+On Windows and Mac if version 2.7 is not installed, you can download the latest
+Python 2.7.x here https://www.python.org/downloads/ :
 
-Download the .msi installer for Windows or the .dmg archive for Mac.
-Open and run the installer using all the default options.
+* Download the .msi installer for Windows or the .dmg archive for Mac.
+* Open and run the installer using all the default options.
+* On Windows, make sure you install Python in the default c:\Python27 and not
+  on another drive.
 
 
-INSTALLATION
+Installation
 ------------
-Checkout or download and extract the AboutCode tool from:
-    https://github.com/dejacode/about-code-tool/
+Download the AboutCode tool from a released version at:
+    https://github.com/dejacode/about-code-tool/releases
+
+Extract the archive to a directory and open a command prompt or shell in this
+directory. Then on Linux or Mac run::
+
+    source configure
+
+And on Windows::
 
-To install all the needed dependencies in a virtualenv, run (on posix)::
-    source configure 
-or on windows::
     configure
 
 
-TESTS
------
-To verify that everything works fine you can run the test suite with::
-    python setup.py test
+For instance on Linux the whole installation would be like this::
+
+   $ wget https://github.com/dejacode/about-code-tool/archive/v2.0.0.zip
+   $ unzip  v2.0.0.zip
+   $ cd about-code-tool-2.0.0/
+   $ source configure
+
+On Windows, the whole installation would be like this:
 
+ * Download and extract https://github.com/dejacode/about-code-tool/archive/v2.0.0.zip
+ * open a command prompt and cd to the directory where the zip extraction directory
+ * run configure
 
-USAGE
+
+
+Later on, if opening a new shell or command prompt on an already installed 
+AboutCode you need to **activate** this installation.
+
+On Linux or Mac, run this::
+   source bin/activate
+
+On Windows, run this::
+   bin\activate
+
+
+
+Usage
 -----
-The ABOUT tool command syntax is:
+Once installed, the AboutCode tool is used from the command line.
+There are three scripts: about.py, genabout.py and genattrib.py.
+Once you have installed or activated AboutCode, the scripts are invoked from a
+shell or command prompt in this way::
+
+    $ python about_code_tool/about.py <options ....>
+
+
+See docs/UsingAboutCodetoDocumentYourSoftwareAssets.pdf for a detailed
+documentation and tutorial or read on the quick instructions below.
+
 
-**about.py**
+**Using the about.py script**
+
+The about.py script is used to collect existing ABOUT files, validate that
+they are correct and collect inventories of the documented components in a CSV
+file.
 
 ::
 
     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_path can be a file or directory containing .ABOUT files.
+    output_path is a file with a .csv extension.
 
     Options:
       -h, --help            Display help
@@ -92,20 +134,26 @@ The ABOUT tool command syntax is:
 
 Example::
 
-    $ python about.py ./thirdparty_code/ thirdparty_about.csv
+    $ python about_code_tool/about.py ./thirdparty/ thirdparty_about.csv
+
 
-In this example, the .ABOUT files in the directory /thirdparty_code/ will
+In this example, the .ABOUT files in the directory thirdparty/ will
 be parsed and validated to collect the data they contain. The collected
 information will be saved to the CSV file named "thirdparty_about.csv".
 
-**genabout.py**
+
+
+**Using the genabout.py script**
+
+The genabout.py script is used to generate new ABOUT files by using a CSV file
+as an input.
 
 ::
 
     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_path is a CSV file using the same format as the CSV created with about.py
+        output_path is a directory where the new .ABOUT files are generated
     
     
     Options:
@@ -131,39 +179,47 @@ information will be saved to the CSV file named "thirdparty_about.csv".
                             Copy the 'license_text_file' from the directory to the generated location
                             License path - License text files path
     
-      --mapping             Configure the mapping key from the MAPPING.CONFIG
+      --mapping             Use the mapping between columns names in your CSV and the ABOUT field
+                            names as defined in the MAPPING.CONFIG mapping configuration file.
     
-      --extract_license=EXTRACT_LICENSE
+      --extract_license
                             Extract License text and create <license_key>.LICENSE side-by-side
-                                with the .ABOUT from DJE License Library.
-                            api_url - URL to the DJE License Library
-                            api_username - The regular DJE username
-                            api_key - Hash attached to your username which is used to authenticate
-                                        yourself in the API. Contact us to get the hash key.
+                            with the generated .ABOUT file using data fetched from a DejaCode License Library.
+                            The following additional options are required:
+                            --api_url - URL to the DejaCode License Library API endpoint
+                            --api_username - DejaCode username
+                            --api_key - DejaCode API key for this username
     
                             Example syntax:
-                            genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key'
+                            python about_code_tool/genabout.py --extract_license --api_url='api_url' --api_username='api_username' --api_key='api_key'
 
 
 Example::
 
-    $ python genabout.py thirdparty_code.csv /tmp/thirdparty_about/
+    $ mkdir tmp
+    $ python about_code_tool/genabout.py thirdparty_code.csv tmp/thirdparty_about
 
-In this example, the tool will look at the "thirdparty_code.csv" and generate
-the .ABOUT files in the directory /tmp/thirdparty_about/.
+In this example, the tool will use the list in the "thirdparty_code.csv" file
+and generate .ABOUT files in a directory tmp/thirdparty_about/
 
 
-**genattrib.py**
+
+
+**Using the genattrib.py script**
+
+The genattrib.py script is used to generate a credit and license attribution
+documentation in HTML from a directory containing .ABOUT files.
 
 ::
 
     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.
-    
-    
+
+        input can be a file or directory.
+        output of rendered template must be a file (e.g. .html).
+        component_list is an optional .csv file with an "about_file" column.
+            It is used to limit the attribution generation to the subset of 
+            ABOUT files listed here.
+
     Options:
       -h, --help            Display help
       -v, --version         Display current version, license notice, and copyright notice
@@ -181,7 +237,7 @@ the .ABOUT files in the directory /tmp/thirdparty_about/.
 
 Example::
 
-    $ python genattrib.py /tmp/thirdparty_about/ /tmp/thirdparty_attribution/attribution.html thirdparty_code.csv
+    $ python about_code_tool/genattrib.py tmp/thirdparty_about/ tmp/attribution.html thirdparty_code.csv
 
 In this example, the tool will look at the .ABOUT files listed in the "thirdparty_code.csv" 
 from the /tmp/thirdparty_about/ and then generate the attribution output to
@@ -190,7 +246,9 @@ from the /tmp/thirdparty_about/ and then generate the attribution output to
 
 (See USAGE for a details explaining of each scripts and options.)
 
-HELP and SUPPORT
+
+
+Help and Support
 ----------------
 If you have a question or find a bug, enter a ticket at:
 
@@ -201,19 +259,22 @@ For issues, you can use:
     https://github.com/dejacode/about-code-tool/issues
 
 
-SOURCE CODE
------------
-AboutCode is available through GitHub. For the latest version visit:
+Hacking, tests and source code
+------------------------------
+For the latest stable version visit::
+
     https://github.com/dejacode/about-code-tool
 
+The development takes places in the develop branch. We use the git flow 
+branching model.
 
-HACKING
--------
-We accept pull requests provided under the same license as this tool.
-You agree to the http://developercertificate.org/ 
+**Tests**
 
+You can run the test suite with::
+    python setup.py test
 
-LICENSE
--------
-AboutCode is released under the Apache 2.0 license.
-See (of course) the about.ABOUT file for details.
+
+**Contributing**
+We accept bugs, patches and pull requests for code and documentation provided 
+under the same license (Apache-2.0) as this tool.
+When contributing, you are agreeing to the http://developercertificate.org/ 

about_code_tool/about.py

@@ -46,7 +46,7 @@
 import ntpath
 
 
-__version__ = '2.0.0'
+__version__ = '2.0.1'
 
 # See http://dejacode.org
 __about_spec_version__ = '1.0'

configure

@@ -1,13 +1,29 @@
 #!/bin/bash
 #
-# Copyright (c) 2014 nexB Inc. http://www.nexb.com/ - All rights reserved.
+# Copyright (c) 2015 nexB Inc. http://www.nexb.com/ - All rights reserved.
 #
+################################
+# change these variables to customize this script locally
+################################
+# you can define one or more thirdparty dirs, each prefixed with TPP_DIR
+export TPP_DIR="thirdparty"
+
+# default configurations
+CONF_DEFAULT="etc/conf"
+#################################
 
 CFG_CMD_LINE_ARGS="$@"
 
+if [ "$1" == "--init" ]; then
+    CFG_CMD_LINE_ARGS=$CONF_INIT
+fi
+
 if [ "$1" == "" ]; then
-    # default configuration if not argument is provided
-    CFG_CMD_LINE_ARGS="etc/conf"
+    # default conf if not argument is provided
+    CFG_CMD_LINE_ARGS=$CONF_DEFAULT
 fi
 
-source etc/configure $CFG_CMD_LINE_ARGS
+python2.7 etc/configure.py $CFG_CMD_LINE_ARGS
+if [ -f "bin/activate" ]; then
+    source bin/activate
+fi