diff --git a/README.md b/README.md index 271acf6..1853a37 100644 --- a/README.md +++ b/README.md @@ -15,28 +15,84 @@ A command-line tool (and Python library) to generate customized exports from the Installation & Quick Start -------------------------- -0a\. Install [Python 3](https://www.python.org/downloads/). This tool is [tested with Python 3.6, 3.7, and 3.8](https://app.travis-ci.com/dimagi/commcare-export). +Following commands are to be run on a terminal or a command line. -0b\. Sign up for [CommCare HQ](https://www.commcarehq.org/) if you have not already. +Once on a terminal window or command line, for simplicity, run commands from the home directory. -1\. Install CommCare Export via `pip` +### Python + +Check for python installed. +This tool is [tested with Python 3.6, 3.7, and 3.8](https://app.travis-ci.com/dimagi/commcare-export). + + +```shell +$ python --version +$ python3 --version +``` +If python is installed, all of its available versions would be listed. + +If python isn't installed, Install Python 3.8 from [this link](https://www.python.org/downloads/). + +## Virtualenv (Optional) + +It is recommended to set up a virtual environment for CommCare Export +to avoid conflicts with other python applications. + +More about virtualenvs on https://docs.python.org/3/tutorial/venv.html + +Setup a virtual environment using: + +```shell +$ python3.8 -m venv .commcare-export-venv # update python version for the one installed +``` + +Activate virtual environment by running: + +```shell +source .commcare-export-venv/bin/activate +``` + +**Note**: virtualenv needs to be activated each time you start a new terminal session or command line prompt. + +For convenience, to avoid doing that, you can create an alias to activate virtual environments in +".commcare-export-venv" directory by adding the following to your +`.bashrc` or `.zshrc` file: + +```shell +alias commcare-export-venv='if [[ -d .commcare-export-venv ]] ; then source .commcare-export-venv/bin/activate ; fi' +``` + +Then you can activate virtual environments with simply typing +```shell +$ commcare-export-venv +``` + +## Install CommCare Export + +Install CommCare Export via `pip` ``` $ python3 -m pip install wheel $ python3 -m pip install commcare-export ``` -2\. Create a project space and application. +## CommCareHQ -3\. Visit the Release Manager, make a build, click the star to release it. +1. Sign up for [CommCare HQ](https://www.commcarehq.org/) if you have not already. -4\. Use Web Apps and fill out some forms. +2. Create a project space and application. -5\. Modify one of example queries in the `examples/` directory, modifying the "Filter Value" column +3. Visit the Release Manager, make a build, click the star to release it. + +4. Use Web Apps and fill out some forms. + +5. Modify one of example queries in the `examples/` directory, modifying the "Filter Value" column to match your form XMLNS / case type. See [this page](https://confluence.dimagi.com/display/commcarepublic/Finding+a+Form%27s+XMLNS) to determine the XMLNS for your form. +Now you can run the following examples: + ``` $ commcare-export \ --query examples/demo-registration.xlsx \