Pull request for #11: Update documentation (#13)

* Update documentation for #11

* Update README for #11

README.md

@@ -1,45 +1,76 @@
 # README
 
+## Requirements
+All requirements must be installed and setup for command line usage. 
+
+* Python 2.7
+* pip (>=10.0)
+
+To initialize the repository as-is, the following software are additionally required:
+
+* git-lfs
+* LyX
+* R
+* Stata
+
+These software are used by the example scripts contained in the repository. By default, the **Setup** instructions below will assume their usage.
+
 ## Setup
-1. Install Python dependencies listed in `requirements.txt` using pip. One way to do this is to use the following bash command from the `setup` subdirectory:
-
+1. Create a `config_local.yaml` file in the root directory. A template can be found in the `setup` subdirectory. See the **Config** section below for further detail.
+
+2. Install Python dependencies listed in the `requirements.txt` file using pip. One way to do this is to use the following bash command from the `setup` subdirectory:
    ```
    pip install --user -r requirements.txt
    ```
 
-2. Run `setup_repository.py`. One way to do this is to use the following bash command from the `setup` subdirectory:
+3. Run the `setup_repository.py` file. One way to do this is to use the following bash command from the `setup` subdirectory:
    ```
    python setup_repository.py
    ```
 
-3. Install Stata dependencies using `setup_stata.do`. One way to do this is to use the following bash command from the `setup` subdirectory:
+4. Install Stata dependencies using the `setup_stata.do` file. One way to do this is to use the following bash command from the `setup` subdirectory:
    ```
    stata-mp -e setup_stata.do
    ```
 
-4. Install R dependencies using `setup_r.r`. One way to do this is to use the following bash command from the `setup` subdirector:y
+5. Install R dependencies using the `setup_r.r` file. One way to do this is to use the following bash command from the `setup` subdirectory:
    ```
    Rscript setup_r.r
    ```
 
-## FAQ
+## Config
+`config.yaml` specifies the minimum required software to initialize the repository. By default, this includes the following software:
+
+   - git-lfs
+   - LyX
+   - R
+   - Stata
+
+All required software must be installed and setup for command line usage. If not, an error message will be raised when attempting to run `setup_repository.py`.
+
+`config_user.yaml` specifies local settings for the user. This includes the following.
 
+1. **External dependencies**: Any files external to the repository should be specified in `config_user.yaml`. Furthermore, any reference to external files in code should be made via an import of `config_user.yaml`.
+
+2. **Executable names**: Required software may be setup for command line usage on your computer with a different executable name from the default. If so, specify the correct executable name in `config_user.yaml`
+
+## FAQ
 1. Help! I'm running into permission errors when trying to install Python dependencies!
 
 <br>
 
-![https://imgs.xkcd.com/comics/python_environment_2x.png](https://imgs.xkcd.com/comics/python_environment_2x.png){:height="50%" width="50%"}
+<img src="https://imgs.xkcd.com/comics/python_environment_2x.png" width="400" height="400">
 
 <br>
 
 The standard bash command for pip installing `requirements.txt` often runs into issues as depending on your Python environment, pip will attempt to install to a root directory (i.e., a directory that by default you should not have write permission)
 ```
-pip install -r requirements.txtt
+pip install -r requirements.txt
 ```
 
-One way to get around this is to include `sudo` (or the Windows equivalent) in your bash command.
+One way to get around this is to include `sudo` (or the Windows equivalent of running in administrative mode) in your bash command.
 ```
-sudo pip install -r requirements.tx
+sudo pip install -r requirements.txt
 ```
 
 However, we caution against this given the potential security risks. Instead, we recommend including the `--user` flag to your bash command.
@@ -56,12 +87,12 @@ The `--user` flag instructs pip to install to a local directory (i.e., a directo
    site.USER_SITE
    ```
 
-   * If this is a directory that you should have write permission to but do not, use the `sudo chown` bash command (or the Windows equivalent) to get ownership.
+   * If this is a directory that you should have write permission to but do not, use the `sudo chown` bash command (or the Windows equivalent of changing ownership through properties) to get ownership.
 
-   * If this is a directory that you should not have write permission to, change your `PYTHONUSERBASE` environment variable to a diretory that you should and do have write permission to.
+   * If this is a directory that you should not have write permission to, change your `PYTHONUSERBASE` environment variable to a directory that you should and do have write permission to.
 
 If you are using Anaconda, we recommend using the following bash command:
 ```
 conda install --file requirements.txt"
 ```
-Note that you may run into issues if any of the Python depencencies are not available on the conda channels. If this is the case, revert back to using `pip`.
+Note that you may run into issues if any of the Python dependencies are not available on the conda channels. If this is the case, revert back to using `pip`.