#44 update readme.

gslab-econ · Apr 21, 2017 · 6950b97 · 6950b97
1 parent 27673f2
commit 6950b97
Showing 1 changed file with 76 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -1,60 +1,84 @@
-Using the repository template
-=============================
-
-#### Pre-requisites:
-
- - Windows `cmd.exe`, Mac OS X `bash`, or Linux `bash`. 
- - [Python 2.X](https://www.python.org) (add to [PATH](https://en.wikipedia.org/wiki/PATH_(variable)))
- - [Stata MP](http://www.stata.com/statamp/) (add to [PATH](https://en.wikipedia.org/wiki/PATH_(variable)))
- - [R](https://www.r-project.org/) (add to [PATH](https://en.wikipedia.org/wiki/PATH_(variable)))
- - [Lyx](https://www.lyx.org/) (add to [PATH](https://en.wikipedia.org/wiki/PATH_(variable)))
- - [SCons](http://scons.org/) (Note that version 2.4.0 or later is best if using the [cache](http://scons.org/doc/2.0.1/HTML/scons-user/c4213.html)).
-    - More information about SCons can be found [here](https://github.com/gslab-econ/ra-manual/wiki/SCons).
- - [git-lfs](https://git-lfs.github.com/)
- - [gslab_tools](https://github.com/gslab-econ/gslab_python) version 3.0.3 or later
- - [GSLab-modified Metropolis beamer theme](https://github.com/gslab-econ/mtheme)
- - [YAML](http://yaml.org/)-related packages/modules:
-     - Stata ado file: [yaml](https://github.com/sergiocorreia/stata-misc/tree/75a8b251bec02ba590c862cc395c4b95077d8a95)
-     - Python module: [PyYAML](http://pyyaml.org/wiki/PyYAML)
-     - R package: [yaml](https://cran.r-project.org/web/packages/yaml/yaml.pdf)
-
-
-The easiest way to install some of the applications above is to use [Homebrew](http://brew.sh/) on Mac OS and [Linuxbrew](http://linuxbrew.sh/) on Linux, as they will set up the `PATH` variable for you, e.g., `brew install scons`.
-
-#### To run:
- - The entire directory:
-    - In the root directory, type `scons` in the command line. This should run everything that is flagged as being modified or with dependencies that have been modified.
- - A single directory of targets:
-    - `scons build/data` will re-build the `build/data` folder if it is out of sync, without rebuilding other files.
- - A single target file:
-    - `scons build/paper/paper.pdf` will re-run only the code needed to update `build/paper/paper.pdf` without rebuilding other files.
-
-See [here](https://github.com/gslab-econ/gslab_python/tree/master/gslab_scons) for directions on making a 'release'.
-
-#### Copy the template:
-In order to create a new repository using this template, either
-
-- First, either:
-	- Fork this repository
-	- Create an empty repository in GitHub and clone it locally. Copy the contents of this template into the empty repository. Make sure to exclude the `.git` folder, but include the `.gitattributes` and `.gitignore` files. Re-run the entire directory using `Scons`. Commit and push to the new repository.
-- Setup a `user-config.yaml` in the root of the directory (note that this file should not be versioned):
-    - MacOS or Linux minimal working example
-    ```
-    stata_flavor: statamp
-    cache: /Users/leviboxell/Google Drive/cache/template
-    ```
-	- Windows 10 minimal working example (note the quotation marks)
+# GSLab Template
+
+The GSLab Template is a minimum working example of the tools and organization used by projects in the GSLab. We use SCons and a few custom builders to execute scripts and track dependencies in a portable and flexible manner.   
+
+## Prerequisites
+
+You'll need the following to run the template. [Homebrew](https://brew.sh/) for mac, [Linuxbrew](http://linuxbrew.sh/) for linux, and [pip](https://docs.python.org/2.7/installing/) make this easier.   
+* Windows `cmd.exe`, Mac OS X `bash`, or Linux `bash`. Most users will have these one of these as standard.
+* [Python 2.X](https://wiki.python.org/moin/BeginnersGuide/Download) for [windows](https://docs.python.org/2/using/windows.html), [mac](https://docs.python.org/2/using/mac.html) or [linux](https://docs.python.org/2/using/unix.html).
+    * [gslab_python](https://github.com/gslab-econ/gslab_python) version 4.0.0 or later of our python module with custom scons builders. 
+    * [PyYAML](http://pyyaml.org/wiki/PyYAML) a python module for parsing yaml files. 
+* [SCons](http://scons.org/pages/download.html). We recommend version 2.4 or later, but any will do.  
+* [git](https://git-scm.com/downloads) for version control.
+    * [git-lfs](https://git-lfs.github.com/) for versioning large files. 
+    * You'll need both git and git-lfs to clone the repository. 
+* [LyX](https://www.lyx.org/Download) (with instructions for LaTeX) the document processor. 
+    * Add LyX to your PATH for [windows](http://www.computerhope.com/issues/ch000549.htm), [mac](http://hathaway.cc/post/69201163472/how-to-edit-your-path-environment-variables-on-mac), and [linux](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux).
+* [Stata](http://www.stata.com/) a proprietary data analysis software. 
+    * Add Stata to your PATH for [windows](http://www.computerhope.com/issues/ch000549.htm), [mac](http://hathaway.cc/post/69201163472/how-to-edit-your-path-environment-variables-on-mac), and [linux](http://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux).
+    * [yaml](https://github.com/gslab-econ/gslab_stata) a Stata ado file for parsing yaml files. FIX THIS URL. 
+
+## Getting started
+
+1. Open a shell, clone the repository, and navigate to its root.
     ```
-    stata_flavor: "%STATAEXE%"
-    cache: C:\Users\Levi Boxell\Google Drive\cache\template
+    git clone https://github.com/gslab-econ/template.git
+    cd template
     ```
-    
-    
-#### License
+2. You're ready to go. We'll prompt you to enter any information necessary and store it in `user-config.yaml` as your scripts run. 
+    * To build everything that has been modified or with dependencies in the repository that have been modified.
+        ```
+        scons
+        ```
+    * To build everything in a single directory of targets that has been modified and all of their dependencies that have been modified.
+        ```
+        scons build/path/to/directory
+        ```
+    * To build a single target that has been modified and all of its dependencies that have been modified.
+        ```
+        scons build/path/to/file.ext
+        ```
+
+## Copying the template
+
+If you want to create a repository with the same structure as this template you can fork it. If you want a repository without any of our git history, follow these instructions. 
+* Create an empty repository in GitHub and clone it. 
+* Copy the contents of this template into the empty repository. Make sure to exclude the `.git` folder, but include the `.gitattributes` and `.gitignore` files. 
+* Create a `user-config.yaml` file and run `scons`. 
+* Commit the changes and push to the new repository.
+
+## FAQ 
+
+##### What is `user-config.yaml`?
+
+Each user is allowed to have different local specifications: We don't put any restrictions on where you keep large files, what you call your executables, or how you manage shared directories. We do need to find these things, and that's what `user-config.yaml` is for. Each user maintains an unversioned [yaml file](http://yaml.org/) with these sorts of specifications. Each script uses its associated yaml-parsing module to read these specifications each time the script is run. 
+
+##### What do I put in `user-config.yaml`?
+
+There's no "default" for `user-config.yaml` because it depends on system specifications and user preferences. Two things we do recommend keeping in `user-config.yaml` are the name of your Stata executable—which we'll prompt you to enter if necessary—and the location of a [SCons cache directory](http://scons.org/doc/2.0.1/HTML/scons-user/c4213.html)—if you have one. An example where Example_User is running a factory-fresh StataMP and has local access to a directory named cache/template on Dropbox would be 
+```YAML
+stata_exec: statamp # StataMP-64.exe on windows
+cache: /Users/Example_User/Dropbox/cache/template
+```
+
+##### Can I only use Stata for data analysis?
+
+Nope, we have custom builders for Python and R, and you can use them with the same syntax as the Stata builder. If you're using R, make sure it's been added to your PATH and that you have a yaml-parsing package, such as [yaml](https://cran.r-project.org/web/packages/yaml/yaml.pdf). 
+
+##### Can I write in LaTeX?
+
+We don't have a custom builder for latex. You can still write in it, but you will have to use [SCons's native builder](http://www.scons.org/doc/0.96.91/HTML/scons-user/a5334.html).
+
+##### Can I release to GitHub?
+
+Yes, see [here](https://github.com/gslab-econ/gslab_python/tree/master/gslab_scons) for directions on making a release.
+
+## License
 
 The MIT License (MIT)
 
-Copyright (c) 2016 Matthew Gentzkow, Jesse Shapiro
+Copyright (c) 2017 Matthew Gentzkow, Jesse Shapiro
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: