Merge pull request #733 from ElectionDataAnalysis/issue728-installation-instructions

Expand installation instructions

Author: sfsinger19103

docs/Installation.md

@@ -0,0 +1,25 @@
+# Installation Instructions
+
+## Environment
+You will need:
+ * `python3.9` 
+ * `postgresql`
+ * all python packages given in [requirements.txt](../requirements.txt), and any packages those packages may require
+
+Not absolutely required, but recommended, is a package manager, such as `homebrew` for macOS.
+
+### python3.9   
+If your environment has a `python` command without a specified version, that `python` may or may not point to `python3.9`. In linux-flavored shells, you can check the version with the command `python --version`. Similarly, your system may have a `python3` command, whose version can be checked with `python3 --version`.
+
+### postgresql
+If postgresql is present, the command `postgres --version` will yield the version number; otherwise the command will fail. The `electiondata` package has been tested with postgres version 13, but probably any reasonably recent version will do. If `postgresql` is not present, you should be able to install it with any reasonable package manager. (On macOS with package manager `homebrew`, use the command `brew install postgresql`) The default values you will need to connect to your `postgresql` instance are:
+ * host: `localhost`
+ * port: `5432`
+ * user: `postgres`
+ * password: (leave the password blank)
+
+### python packages
+To install the required packages, run `python3.9 -m pip install -r requirements.txt` from the [root folder of the repository](../).  Because some of the required packages have requirements of their own, which may or may not be installed already, your system prompt you to install some other packages. If so, install the suggested packages and try `python3.9 -m pip install -r requirements.txt` again.
+
+## Installation
+From the [root folder of the repository](../) run `python3.9 setup.py install`. (You may be able to use `python setup.py install` or `python3 setup.py install` instead, if those point to `python3.9`, as described above.)

docs/User_Guide.md

@@ -1,13 +1,16 @@
 # How to Use the System
 ## Environment
-You will need `python3.9`. If you use the alias `python`, make sure it points to `python3.9`.
+You will need:
+ * `python3.9`. 
+ * `postgresql`. You do *not* need to create a database; you just need to make sure a `postgresql` is installed, and you need to have the hostname, port and login credentials with default permissions. 
+ * all required python packages: run `python3.9 -m pip install -r requirements.txt` from the root folder of the repository.
+   
+For more detail, see the [Installation Instructions](./install.md).
 
-The system runs out of the box with a postgresql database; to use other varieties of SQL, you will need to modify the routines in the `database` module. 
+To use other varieties of SQL, you would need to modify the routines in the `database` module.
 
 ## Installation
-From the root folder of your repository run `python3 setup.py install` (or if `python` is an alias for `python3` on your system, `python setup.py install`).
-
-## Setting up
+The one-line version: From the root folder of your repository run `python3 setup.py install`. For more detail, see the [Installation Instructions](./install.md).
 
 ### Main parameter file
 You will need a main parameter file to specify paths and database connection information specific to your local computing environment. This file is necessary for the three main classes: