Maintenance scheduled for Thursday, September 24th at 15:00 MDT. Expected downtime <1 hour.

Merge branch '43-update-tutorials' into 'master'

Resolve "Update tutorial"

Closes #43

See merge request mdomanski/fluegg!37
parents 6aa8e0a8 ff0f5f7f
# Setting up the development environment on Windows
## 1. Download and install Miniconda
Miniconda is a Python distribution and environment manager. Miniconda will help
you install the correct packages and Python version to run the FluEgg code.
* Download [Miniconda](https://docs.conda.io/en/latest/miniconda.html). Be sure
to download the 64-bit Python 3.7 version.
* Run the installer. Install it for "Just me" when asked. This does not require
administrative privileges. **Do not** install Miniconda for "all users".
## 2. Download and install Git
## 1 Download and install Git
Git is a source control manager. It tracks changes made to the code and helps
to keep versions of the code organized.
* Download [Git](https://git-scm.com/). Similar to installing Miniconda, install
Git on your profile. This does not require administrative privileges. **Do
not** install Git for all users.
* Download [Git](https://git-scm.com/). Install Git on your profile.
This does not require administrative privileges.
**Do not** install Git for all users.
## 3. Create an SSH key and add it to your GitLab account
## 2. Create an SSH key and add it to your GitLab account
In order to securely communicate with the remote repository server, you'll need
to set up SSH.
......@@ -31,8 +20,8 @@ to set up SSH.
* Create an SSH key and add it to your GitLab account by following the
instructions beginning [here](https://code.usgs.gov/help/ssh/README.md#generating-a-new-ssh-key-pair).
Follow the instructions under **Generating a new SSH key pair** and **Adding an
SSH key to your GitLab account**.
Follow the instructions under **Generating a new SSH key pair** and
**Adding an SSH key to your GitLab account**.
* You want to use RSA when generating a new SSH key pair.
......@@ -42,40 +31,43 @@ SSH key to your GitLab account**.
ssh -T git@code.usgs.gov
```
## 4. Clone the repository
## 3. Clone the repository
Cloning the repository downloads a copy of the Git repository to your
local machine. This repository contains a history of changes, and most
importantly, the FluEgg code. Cloning the repository will also create a
reference from your local repository to the remote repository on code.usgs.gov.
This process may be done with either Windows Command Prompt or git bash. This
tutorial will use Command Prompt.
* Open Anaconda Prompt (available after installing Miniconda) and navigate to
the directory where you want to keep the FluEgg repository. In the following
instructions, `path-to-sources` is this directory.
* Open Command Prompt and navigate to the directory where you want to keep the
FluEgg repository by using the `cd` command. In the following instructions,
`path-to-sources` is this directory.
* Clone the repository using the following command (where `(base)
C:\path-to-sources>` is the command prompt).
* Clone the repository using the following command (where
`C:\path-to-sources>` is the command prompt).
```
(base) C:\path-to-sources>git clone git@code.usgs.gov:FluEgg/fluegg.git
C:\Users\user>cd C:\path-to-sources
C:\path-to-sources>git clone git@code.usgs.gov:FluEgg/fluegg.git
```
## 5. Create and activate the fluegg conda environment
## 4. Create and activate the fluegg venv environment
In this step, you will create an Anaconda environment that contains the version
In this step, you will create a venv environment that contains the version
of Python and versions of packages that are known to work with the FluEgg code
base.
* `cd` into the `fluegg` directory that was created after cloning the FluEgg
repository.
* Create an environment by running `python -m venv env`
```
(base) C:\path-to-sources>cd fluegg
```
* Create an environment by running `conda create --name fluegg`
```
(base) C:\path-to-sources\fluegg>conda create --name fluegg
C:\path-to-sources>cd fluegg
C:\path-to-sources\fluegg>python -m venv env
```
See [Creating an environment with commands](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands)
on the conda help page for more info.
See [Creating virtual environments](https://docs.python.org/3/library/venv.html#creating-virtual-environments)
on the venv help page for more info.
* Activate the fluegg environment
......@@ -83,31 +75,22 @@ You'll have to take this step every time you want to work in the FluEgg
development environment.
```
(base) C:\path-to-sources\fluegg>conda activate fluegg
(fluegg) C:\path-to-sources\fluegg>
C:\path-to-sources\fluegg>env\Scripts\activate
(env) C:\path-to-sources\fluegg>
```
## 6. Install the fluegg environment
## 5. Install the fluegg environment
The fluegg environment contains Python packages that the fluegg package is
known to work with.
First, install Python. This will also install supporting libraries and
programs, including pip.
```
(fluegg) C:\path-to-sources\fluegg>conda install python==3.7.3
```
If conda throws an SSL error, see [this document](doi-sslintercept.md)
Next, install the packages in the environment using pip.
First, install the packages in the environment using pip.
```
(fluegg) C:\path-to-sources\fluegg>pip install -r requirements.txt
(env) C:\path-to-sources\fluegg>pip install -r requirements.txt
```
## 7. Install the fluegg package
## 6. Install the fluegg package
In order for the Python interpreter in the fluegg environment to have "global"
access to the fluegg package, you'll have to install the package within the
......@@ -115,13 +98,13 @@ fluegg environment.
* Install the fluegg package with pip
```
(fluegg) C:\path-to-sources\fluegg>pip install -e .
(env) C:\path-to-sources\fluegg>pip install -e .
```
The `-e` option tells pip to install the fluegg package in "editable" mode.
See ["Editable" installs](https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs) for more info.
## 8. Run the FluEgg unit tests
## 7. Run the FluEgg unit tests
Running the unit tests will ensure the environment is set up and the FluEgg
code is working correctly.
......@@ -129,12 +112,12 @@ code is working correctly.
* From the fluegg directory, run `python setup.py test` from the
command line. The output should look something like the below text.
```
(fluegg) C:\path-to-sources\fluegg>python setup.py test
(env) C:\path-to-sources\fluegg>python setup.py test
*test output... maybe some warnings but it doesn't matter so long as the tests
pass*
----------------------------------------------------------------------
Ran 40 tests in 3.452s
Ran 43 tests in 3.452s
OK
```
......@@ -142,7 +125,7 @@ OK
The tests passing is a clear indicator that the FluEgg environment has been set
up correctly. You're ready to begin working with the code.
## 9. Build the code documentation
## 8. Build the code documentation
Currently, only the docstrings within the FluEgg code are available in the
documentation.
......@@ -151,7 +134,7 @@ To build the documentation, run the command `python setup.py build_sphinx` from
the prompt. The output will look something like the below text.
```
(fluegg) C:\path-to-sources\fluegg>python setup.py build_sphinx
(env) C:\path-to-sources\fluegg>python setup.py build_sphinx
running build_sphinx
*build process output*
The HTML pages are in docs\_build\html.
......@@ -161,3 +144,29 @@ To view the generated HTML documentation, open the file
`path-to-sources\fluegg\docs\_build\html\index.html` in a browser. Again,
`path-to-sources\fluegg` is the top-level directory of the FluEgg project on
your machine.
## 9. Build an executable
The FluEgg repository also contains code for the user interface. This user interface
may be tested by running the following command:
```
(env) C:\path-to-source\fluegg>python app.py
```
For more information on how to use the user interface, see the FluEgg Manual.
In order to build the user interface as it appears through the command line,
the python module `pyinstaller` will be used. To start, enter the command:
```
(env) C:\path-to-source\fluegg>pyinstaller app.spec
```
The process of building the program may take a couple minutes. When complete,
attempt to run the build now stored in the auto-generated `dist` folder.
The executable will be named with a timestamp to distinguish between different
builds. If there are any issues during building or if the executable file
fails to run, check that all of the code requirements are satisfied using the command
`pip list` and see [Using Spec Files](https://pyinstaller.readthedocs.io/en/stable/spec-files.html)
from the pyinstaller manual.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment