diff --git a/README.md b/README.md index 76bf6dc4..f6fe2ec2 100644 --- a/README.md +++ b/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!
-![https://imgs.xkcd.com/comics/python_environment_2x.png](https://imgs.xkcd.com/comics/python_environment_2x.png){:height="50%" width="50%"} +
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`. \ No newline at end of file +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`. \ No newline at end of file