Update docs (big cleanup), add tooling

.gitignore

@@ -52,6 +52,7 @@ __pycache__
 _pycache_
 augur/bin
 .pytest_cache
+.ipynb_checkpoints
 
 # Node #
 ########

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/metrics/upstream"]
+	path = docs/metrics/upstream
+	url = https://github.com/chaoss/metrics.git

CONTRIBUTING.md

@@ -6,26 +6,18 @@ Fork, then clone the repo:
 
     git clone git@github.com:your-username/augur.git
 
-Make your change and push to your fork. Then, [submit a pull request][pr].
+Make your change.
 
-[pr]: https://github.com/thoughtbot/factory_girl_rails/compare/
+When you are done making changes, run `make docs` to rebuild the documentation.
 
-At this point you're waiting on us. We like to at least comment on pull requests
-within three business days (and, typically, one business day).
+Push to your fork.
 
-Some things that will increase the chance that your pull request is accepted:
+Then, [submit a pull request](https://github.com/OSSHealth/augur/compare)
 
-* Inform the [mailing list][ml] of your pull request.
-* Use [Markdown][md] (we can fix this for you)
-
-[ml]: https://lists.linuxfoundation.org/pipermail/oss-health-metrics/
-[commit]: https://guides.github.com/features/mastering-markdown/#syntax
+At this point you're waiting on us. We like to at least comment on pull requests
+within three business days (and, typically, one business day).
 
 # Additional Resources
 
-* [CHAOSS Website][chaoss]
-* [CHAOSS Metrics Wiki][wiki]
-
-
-[chaoss]: https://chaoss.community/
-[wiki]: https://wiki.linuxfoundation.org/chaoss/metrics
+* [CHAOSS Website](https://chaoss.community/)
+* [CHAOSS Metrics Wiki](https://github.com/chaoss/metrics)

Dockerfile

@@ -4,7 +4,7 @@ FROM tiangolo/uwsgi-nginx-flask:python3.6
 
 ENV STATIC_INDEX 1
 
-COPY ./packaging/docker/uwsgi.ini /app/uwsgi.ini
+COPY ./util/packaging/docker/uwsgi.ini /app/uwsgi.ini
 COPY ./frontend/public /app/static
 
 RUN mkdir /augur

Makefile

@@ -1,44 +1,49 @@
-.PHONY: all test clean install install-dev python-docs api-docs docs dev-start dev-stop dev-restart monitor monitor-backend monitor-frontend download-upgrade upgrade frontend install-ubuntu-dependencies
+.PHONY: all test clean install install-dev python-docs api-docs docs dev-start dev-stop dev-restart monitor monitor-backend monitor-frontend download-upgrade upgrade frontend install-ubuntu-dependencies metric-status edit-metrics-status update-upsteam
 
 SERVECOMMAND=gunicorn -w`getconf _NPROCESSORS_ONLN` -b0.0.0.0:5000 augur.server:app
-CONDAUPDATE=if ! conda activate augur; then conda env create -n=augur -f=environment.yml && conda activate augur; else conda env update -n=augur -f=environment.yml && conda activate augur; fi;
+CONDAUPDATE=if ! source activate augur; then conda env create -n=augur -f=environment.yml && source activate augur && python -m ipykernel install --user --name augur --display-name "Python (augur)"; else conda env update -n=augur -f=environment.yml && conda activate augur; fi;
 
 default:
 	@ echo "Commands:"
-	@ echo
-	@ echo "    install          Installs augur using pip"
-	@ echo "    install-dev      Installs augur's developer dependencies (requires npm and pip)"
-	@ echo "    install-msr      Installs MSR14 dataset"
-	@ echo "    upgrade          Pulls newest version and installs"
-	@ echo "    test             Run pytest unit tests"
-	@ echo "    serve            Runs using gunicorn"
-	@ echo "    dev              Starts the full stack and monitors the logs"
-	@ echo "    dev-start        Runs 'make serve' and 'brunch w -s' in the background"
-	@ echo "    dev-stop         Stops the backgrounded commands"
-	@ echo "    dev-restart      Runs dev-stop then dev-restart"
-	@ echo "    python-docs      Generates new Sphinx documentation"
-	@ echo "    api-docs         Generates new apidocjs documentation"
-	@ echo "    docs             Generates all documentation"
-	@ echo "    frontend         Builds frontend with Brunch"
-	@ echo "    build            Builds documentation and frontend - use before pushing"
-	@ echo "    update-deps      Generates updated requirements.txt and environment.yml"
+	@ echo "    install                Installs augur using pip"
+	@ echo "    install-dev            Installs augur's developer dependencies (requires npm and pip)"
+	@ echo "    install-msr            Installs MSR14 dataset"
+	@ echo "    upgrade                Pulls newest version and installs"
+	@ echo "    test                   Run pytest unit tests"
+	@ echo "    serve                  Runs using gunicorn"
+	@ echo "    dev                    Starts the full stack and monitors the logs"
+	@ echo "    dev-start              Runs 'make serve' and 'brunch w -s' in the background"
+	@ echo "    dev-stop               Stops the backgrounded commands"
+	@ echo "    dev-restart            Runs dev-stop then dev-restart"
+	@ echo "    metric-status          Shows the implementation status of CHAOSS metrics"
+	@ echo "    edit-metrics-status    Edits the JSON file that tracks CHAOSS metrics implementation status"
+	@ echo "    python-docs            Generates new Sphinx documentation"
+	@ echo "    api-docs               Generates new apidocjs documentation"
+	@ echo "    docs                   Generates all documentation"
+	@ echo "    frontend               Builds frontend with Brunch"
+	@ echo "    build                  Builds documentation and frontend - use before pushing"
+	@ echo "    update-deps            Generates updated requirements.txt and environment.yml"
+
 
 install:
-		bash -lc '$(CONDAUPDATE) pip install --upgrade .'
+		bash -c '$(CONDAUPDATE) pip install --upgrade .'
 
 install-dev:
-		bash -lc '$(CONDAUPDATE) pip install pipreqs sphinx; npm install -g apidoc brunch; pip install -e .; cd frontend/ && npm install'
+		bash -c '$(CONDAUPDATE) pip install pipreqs sphinx; npm install -g apidoc brunch; pip install -e .; cd frontend/ && npm install'
 
 install-dev-admin:
-	bash -lc '$(CONDAUPDATE) sudo pip install pipreqs sphinx; sudo npm install -g apidoc brunch; pip install -e .; cd frontend/ && npm install'
+	bash -c '$(CONDAUPDATE) sudo pip install pipreqs sphinx; sudo npm install -g apidoc brunch; pip install -e .; cd frontend/ && npm install'
 
 install-msr:
 		@ ./docs/install-msr.sh
 
 download-upgrade:
 		git pull
 
-upgrade: download-upgrade install
+update-upsteam: 
+	git submodule update --init --recursive
+
+upgrade: download-upgrade update-upsteam dev-install
 		@ echo "Upgraded."
 
 dev-start: dev-stop
@@ -120,6 +125,14 @@ ifdef CONDA
 		conda env export > environment.yml
 endif
 
+metrics-status: update-upsteam
+	@ cd docs/metrics/ && python status.py | less
+
+edit-metrics-status:
+	$(EDITOR) docs/metrics/status.json
+
+jupyter: check-test-env
+		@ bash -c 'source activate augur; cd notebooks; jupyter notebook'
 
 install-ubuntu-dependencies:
 	@ echo "Downloading NodeSource Installer..."

README.md

@@ -5,34 +5,44 @@ branch | status
 master | [![Build Status](https://travis-ci.org/OSSHealth/augur.svg?branch=master)](https://travis-ci.org/OSSHealth/augur)
    dev | [![Build Status](https://travis-ci.org/OSSHealth/augur.svg?branch=dev)](https://travis-ci.org/OSSHealth/augur)
 
+
+
 ## About Augur
 
 Augur is focused on prototyping open source software metrics. 
 
 Functionally, Augur is a prototyped implementation of the Linux Foundation's [CHAOSS Project](http://chaoss.community) on [open source software metrics](https://github.com/CHAOSS/metrics). Technically, Augur is a [Flask Web Application](http://augurlabs.io), [Python library](https://osshealth.github.io/augur/python/build/html/index.html) and [REST server](https://osshealth.github.io/augur/api/index.html) that presents metrics on open source software development project health and sustainability. Hosting the Augur project requires 
 
+
+
 ## Installing Augur 
 
+#### Dependencies
  - The [GHTorrent database](http://ghtorrent.org/downloads.html). 
-    - You can use the *much smaller [MSR14 dataset](http://ghtorrent.org/msr14.html) for a quick look or to perform development.  
+    - You can use the *much* smaller [MSR14 dataset](http://ghtorrent.org/msr14.html) for a quick look or to perform development.
+ - A [GitHub Access Token (no write access required)](https://github.com/settings/tokens)
 
-To **get Augur up and running quickly**, install our docker image. [Installation Instructions for Docker Image of Augur](./docker-install.md)
+#### Docker Installation
+To get Augur up and running quickly, [install our Docker image](./docs/docker-install.md).
 
-To **contribute to our code base routinely**, we recommended that developers configure Augur on their local workstations. Get started with our [Installation Instructions for Developers](./dev-install.md), and then check out our [development guide](./DEV-GUIDE.md)
+#### Local Installation
+To contribute to our code base routinely, we recommended that developers configure Augur on their local workstations. Get started with our [installation instructions for developers](docs/dev-install.md), and then check out our [development guide](docs/dev-guide/dev-guide-overview.md)
 
 **Both configurations require a MariaDB database with a subset of the GHTorrent dataset** 
 
--------
 
-# Augur Development
-To contribute to Augur, check out our [development guide](./DEV-GUIDE.md) and our [notes on making contributions](CONTRIBUTING.md). Also, please note our [code of conduct](CODE_OF_CONDUCT.md). We want Augur to be open for everyone and to be a welcoming development community. 
+
+## Augur Development
+To contribute to Augur, check out our [tutorial](docs/tutorial.md), [development guide](docs/dev-guide/dev-guide-overview.md) and [notes on making contributions](CONTRIBUTING.md). Also, please note our [code of conduct](CODE_OF_CONDUCT.md). We want Augur to be a welcoming development community that is open for everyone. 
+
+
 
 ## Roadmap
 Our technical, outreach, and academic goals [roadmap](https://github.com/OSSHealth/augur/wiki/Release-Schedule).
 
----------------------
 
-# License and Copyright
+
+## License and Copyright
 Copyright © 2018 University of Nebraska at Omaha, University of Missouri and CHAOSS Project at the Linux Foundation
 
 Augur is free software: you can redistribute it and/or modify it under the terms of the MIT License as published by the Open Source Initiative. See the file [LICENSE](LICENSE) for more details.