Merge pull request #41 from CodeForPhilly/readme-to-docs

docs: merge README content into docs

Author: themightychris

README.md

@@ -1,4 +1,5 @@
 # CHIME
+
 The **C**OVID-19 **H**ospital **I**mpact **M**odel for **E**pidemics
 
 [![CHIME](https://user-images.githubusercontent.com/1069047/76693244-5e07e980-6638-11ea-9e02-1c265c86fd2b.gif)](http://predictivehealthcare.pennmedicine.org/chime)
@@ -7,51 +8,9 @@ Interested in [contributing](https://codeforphilly.github.io/chime/CONTRIBUTING.
 
 Join our [Code For Philly](https://codeforphilly.org/projects/chime) project or our [Slack workspace](https://codeforphilly.org/chat) in the [#covid19-chime-penn](https://codeforphilly.org/chat/covid19-chime-penn) channel if you'd like to chat with us. We'd appreciate your [feedback](http://predictivehealthcare.pennmedicine.org/contact/).
 
-## Development
-To test the app locally just run:
-
-```sh
-streamlit run app.py
-```
-
-This will open a browser window with the app running on port 8000. If you need the app to run on another port, you can edit `.streamlit/config.toml`, or use the magic ENV var, `STREAMLIT_SERVER_PORT` - see [this streamlit issue](https://github.com/streamlit/streamlit/pull/527). So, for example, to run the app on port 1234, you would change the last line of `config.toml` to `port = 1234` or invoke the app like this:
-
-```sh
-STREAMLIT_SERVER_PORT=1234 streamlit run app.py
-```
-
-### With `pipenv`
-```bash
-pipenv shell
-pipenv install
-streamlit run app.py
-```
-
-### With `conda`
-```bash
-conda env create -f environment.yml
-source activate chime
-pip install streamlit
-streamlit run app.py
-```
-
-### Developing with `docker`
-
-Copy `.env.example` to be `.env` and run the container.
-
-```bash
-cp .env.example .env
-docker-compose up
-```
-
-You should be able to view the app via `localhost:8000`. If you want to change the
-port (as described above), then you also have to set `PORT` in the `.env` file.
-
-**NOTE** this is just for usage, not for development--- you would have to restart and possibly rebuild the app every time you change the code.
-
-If you'd like to use `docker-compose` for development, please run `docker-compose up --build` every time you make changes. 
-
-## Deployment
-**Before you push your changes to master make sure that everything works in development mode.**
+## Documentation
 
-Changes merged to `master` will be automatically deployed to [http://penn-chime.phl.io/](http://predictivehealthcare.pennmedicine.org/chime).
+- [Getting Started: Try Online](https://codeforphilly.github.io/chime/getting-started/try-online.html)
+- [Getting Started: Run Locally](https://codeforphilly.github.io/chime/getting-started/run-locally.html)
+- [Contributing: Overview](https://codeforphilly.github.io/chime/CONTRIBUTING.html)
+- [Contributing: Application Development](https://codeforphilly.github.io/chime/contributing/app-dev.html)

docs/SUMMARY.md

@@ -10,6 +10,7 @@
   - Operations Support—*coming soon*
 - Operations
   - [The `chime-live` Cluster](./operations/chime-live-cluster.md)
+  - [Deploy to Heroku](./operations/heroku.md)
   - [Deploy to Your Own Cluster](./operations/byok8s.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
 - [Maintainers](MAINTAINERS.md)

docs/contributing/app-dev.md

@@ -10,14 +10,72 @@
 
 ## Developer Requirements
 
-List out requirements. We should allow for all platforms (MacOS/Windows/Linux)
+The application is built with [Streamlit](https://www.streamlit.io/), Streamlit requires:
 
-Make sure that you have the requirements installed before proceeding.
+- Python 2.7.0 or later / Python 3.6.x or later
+- PIP
+
+See [Streamlit's Getting Started guide](https://docs.streamlit.io/getting_started.html) for detailed information on prerequisites and setup
+
+## Running CHIME Locally
+
+### With `pipenv`
+
+```bash
+pipenv shell
+pipenv install
+streamlit run app.py
+```
+
+### With `conda`
+
+```bash
+conda env create -f environment.yml
+source activate chime
+pip install streamlit
+streamlit run app.py
+```
+
+### Choosing a Different Port
+
+If you need to run the application on a different port than the default (8000), you can export a variable in your shell session to override it with any port number of your choice before running:
+
+```bash
+export STREAMLIT_SERVER_PORT=1234
+streamlit run app.py
+```
 
 ## Project Layout
 
-Explain how the project is laid out so other can pinpoint quickly the core components. Some of these are in progress.
+### Application files
+
+- `script/`: Developer workflow scripts following [GitHub's Scripts To Rule Them All](https://github.com/github/scripts-to-rule-them-all) pattern.
+- `app.py`: Main source for the application
+- `.streamlit/`: [Streamlit config options](https://docs.streamlit.io/cli.html)
+- `.env`: Local environment variables to use when running application, this file is copied from `.env.example` to start you out and then ignored by git
+- `Pipfile`
+- `Pipfile.lock`
+- `environment.yml`
+- `requirements.txt`
+
+### Documentation
+
+- `docs/`: Markdown documentation in [GitBook format](https://gitbookio.gitbooks.io/docs-toolchain/structure.html) used to generate `gh-pages` website at [codeforphilly.github.io/chime](https://codeforphilly.github.io/chime)
+
+### Operations support
+
+- `.github/workflows/`: [GitHub Actions](https://github.com/features/actions) workflows implementing automations driven by GitHub events
+- `.holo/`: [Hologit](https://github.com/JarvusInnovations/hologit) projection configuration, used to generate `gh-pages` branch from content changes in `docs/` tree
+- `k8s/`: Kubernetes manifests for [the `chime-live` cluster](https://codeforphilly.github.io/chime/operations/chime-live-cluster.html)
+- `.env.example`: A starter `.env` file distributed with the project
+- `docker-compose.yml`: Runtime container configuration for running the application locally via Docker
+- `Dockerfile`: Recipe for building Docker container that runs the application
+- `Procfile`: Supports running the application on Heroku
 
 ## Testing
 
+*No testing routine is available yet. If you have thoughts on how to add one, please contribute!*
+
 ## Validating CHIME
+
+*No validation routine is available yet. If you have thoughts on how to add one, please contribute!*

docs/getting-started/run-locally.md

@@ -1,3 +1,40 @@
 # Getting Started: Run Locally
 
-*Coming soon*
+This guide aims to provide the easiest and most reliable method for getting a copy of the application running locally.
+
+If you're a developer looking to do heavier work on the application, check out the [Contributing: Application Development](../contributing/app-dev.md) for a more advanced guide covering practical developer workflows.
+
+## Quickstart with Docker
+
+From the root directory of the repository, you should be able to get up and running with one command:
+
+```bash
+./script/server
+```
+
+This script will:
+
+- Verify that `docker` and `docker-compose` are available on your system
+- Initialize `.env` if needed from `.env.example`
+- Use `docker-compose up` to build and start an instance of the application as a background daemon
+- Print out the URL you can open the app at (usually [http://localhost:8000](http://localhost:8000))
+
+### Running on a Different Port
+
+If you need to run the server on a different, edit the `PORT` option in your `.env` file. You might need to do this if you have something else already running on the default port (8000).
+
+## Updating After Changing Code
+
+If you edit code, or checkout a new branch, the update script will handle all needed steps to refresh your running instance:
+
+```bash
+./script/update
+```
+
+## Shutdown and Cleanup
+
+From the same directory, run this command to shut down the Docker container and clean up any volumes:
+
+```bash
+docker-compose down -v
+```

docs/operations/heroku.md

@@ -0,0 +1,3 @@
+# Operations: Deploy to Heroku
+
+The Heroku instance at [`pennchime.herokuapp.com`](https://pennchime.herokuapp.com/) will be automatically redeployed when changes are merged into the `master` branch off [the `pennsignal/chime` repository](https://github.com/pennsignals/chime).