Pull request for template#60: update Provenance docs, update function args

gslab_scons/README.md

@@ -1,21 +1,23 @@
 ## Notes on release.py
 
-Make a release from an SCons directory by running the following
-from the command line within the directory of interest (e.g. `gslab-econ/template/paper_slides`):
+Make a release from an SCons directory by running the module `release`. 
+
+A user can either run the following from the command line within the directory of interest (e.g. `/paper_slides`) or write a Python script to call the module (see "Python wrapper" section below). If using the command line, run the following:
 
 ```sh
-python -m gslab_scons.release version=<version name here>
+python -m gslab_scons.release version=<version name here> readme=<readme path here>
 ```
 
 where `<version name here>` is the name of the version that 
-will be released. As an example, to release version
-v1.2.1 of a directory, navigate to the root of the directory and run:
+will be released, and `<readme path>` is the path from the current directory
+to the repository readme file (default to `./README.md`). As an example, to release version
+v1.2.1 of a directory with the README file one level up, navigate to the root of the directory and run:
 
 ```sh
-python -m gslab_scons.release version=v1.2.1
+python -m gslab_scons.release version=v1.2.1 readme=../README.md
 ```
 
-An automatic location for release can be specified in `config_user.yaml` with 
+An automatic location for release must be specified in `config_user.yaml` with 
 
 ```yaml
 release_directory: <release location here>
@@ -40,3 +42,21 @@ you can store it in `config_user.yaml` as
 ```yaml
 github_token: <your token here>
 ```
+
+## Provenance
+
+Making a release using this tool will automatically call `make_provenance()` from the module `provenance` to create a `provenance` file (for more details, please see our [RA manual](https://github.com/gslab-econ/ra-manual/wiki/Data-Storage)). 
+
+While calling the `release` module from the command line, one can specify the `detail_limit` argument of `make_provenance()` by adding `detail_limit=<###>` (default to 500).
+
+## Python wrapper
+
+If you wish to wrap the `release` module in a Python script to pass arguments to `make_provenance()`, use the following syntax:
+
+```python
+from gslab_scons import release
+release.main(version = '<version name here>',
+             readme  = '../readme.md')
+```
+
+For a complete list of arguments that you can pass to `release.main()` and `make_provenance()`, visit `release.py` and `provenance.py` respectively. 

gslab_scons/release.py

@@ -6,10 +6,13 @@
 from misc import load_yaml_value, check_and_expand_path
 from provenance import make_provenance
 
-def main(user_yaml = 'config_user.yaml', 
+def main(version = None,
+         user_yaml = 'config_user.yaml', 
          release_files = [],
          prov_excluded_dirs = [],
-         external_provenance = []):
+         external_provenance = [],
+         dont_zip = False,
+         readme = None):
     inspect_repo()
 
     # Extract information about the clone from its .git directory
@@ -22,15 +25,16 @@ def main(user_yaml = 'config_user.yaml',
             raise ReleaseError("Could not find .git/config in the current directory or parent directory.")
 
     # Determine the version number
-    try:
-        version = next(arg for arg in sys.argv if re.search("^version=", arg))
-    except:
-        raise ReleaseError('No version specified.')
-
-    version = re.sub('^version=', '', version)
+    if version is None:
+        try:
+            version = next(arg for arg in sys.argv if re.search("^version=", arg))
+        except:
+            raise ReleaseError('No version specified.')
+        version = re.sub('^version=', '', version)
 
     # Determine whether the user has specified the no_zip option
-    dont_zip    = 'no_zip' in sys.argv
+    if dont_zip == False:
+        dont_zip = 'no_zip' in sys.argv
     zip_release = not dont_zip
 
     # Read a list of files to release to release_dir
@@ -54,11 +58,12 @@ def main(user_yaml = 'config_user.yaml',
     local_release = local_release + version + '/'
 
     # Create provenance file in ./release
-    try:
-        readme = next(arg for arg in sys.argv if re.search("^readme=", arg))
-    except:
-        readme = "readme=./README.md"
-    readme = re.sub('^readme=', '', readme)
+    if readme is None:
+        try:
+            readme = next(arg for arg in sys.argv if re.search("^readme=", arg))
+        except:
+            readme = "readme=./README.md"
+        readme = re.sub('^readme=', '', readme)
 
     # Check provenance options
     find_for_me = 'find_for_me' in sys.argv