Add docs and update readme

.dockerignore

@@ -1 +1,98 @@
-test/
+tests/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+tests/results/coverage*
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+.venv/
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject
+
+# Sphinx
+docs/sphinx/_build
+
+# Prometheus
+.prom

.drone.yml

@@ -1,8 +1,40 @@
 ---
+### YAML Anchors
+
+tox_image: &tox_image
+  image: themattrix/tox:latest
+  volumes:
+    - name: pip_cache
+      path: /root/.cache/pip
+
+### Pipline
+
 kind: pipeline
 name: karrot
-
 steps:
+  - name: lint
+    <<: *tox_image
+    commands:
+      - tox -e lint
+
+  - name: checkstyle
+    <<: *tox_image
+    commands:
+      - tox -e checkstyle
+
+  - name: unit-tests
+    <<: *tox_image
+    commands:
+      - tox -e coverage
+
+  - name: coveralls
+    <<: *tox_image
+    environment:
+      COVERALLS_REPO_TOKEN:
+        from_secret: coveralls_token
+    commands:
+      - tox -e coveralls
+
   - name: release
     image: plugins/docker
     settings:
@@ -17,3 +49,7 @@ steps:
         - latest
     when:
       event: tag
+
+volumes:
+  - name: pip_cache
+    temp: {}

.gitignore

@@ -15,7 +15,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
 lib64/
 parts/
 sdist/
@@ -36,6 +35,7 @@ pip-delete-this-directory.txt
 
 # Unit test / coverage reports
 htmlcov/
+tests/results/coverage*
 .tox/
 .coverage
 .coverage.*
@@ -79,6 +79,7 @@ celerybeat-schedule
 .env
 
 # virtualenv
+.venv/
 venv/
 ENV/
 
@@ -88,5 +89,8 @@ ENV/
 # Rope project settings
 .ropeproject
 
-# Project prod configuration
-app/config/prod.py
+# Sphinx
+docs/sphinx/_build
+
+# Prometheus
+.prom

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+---
+repos:
+  - hooks:
+      - args:
+          - "--safe"
+        id: black
+        language_version: python3.7
+    repo: "https://github.com/ambv/black"
+    rev: 18.9b0
+
+  - hooks:
+      - additional_dependencies:
+          - black==18.9b0
+        id: blacken-docs
+        language_version: python3.7
+    repo: "https://github.com/asottile/blacken-docs"
+    rev: v0.3.0
+
+  - hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: debug-statements
+      - additional_dependencies:
+          - "flake8-bugbear == 18.2.0"
+        id: flake8
+        language_version: python3.7
+    repo: "https://github.com/pre-commit/pre-commit-hooks"
+    rev: v2.0.0

Dockerfile

@@ -3,18 +3,20 @@ FROM python:3.7-stretch as builder
 ENV PYTHONPATH /src:/venv/lib/python3.7/site-packages
 ENV PATH $PATH:/venv/bin
 
+# Copy the source code into the container
+COPY . /src
+
 # Copy files needed to install app requirements
-COPY ./requirements.txt /src/requirements.txt
+# COPY ./requirements.txt /src/requirements.txt
+# COPY ./setup.py /src/setup.py
+# COPY ./karrot/release.py /src/karrot/release.py
 
 # Install app requirements in virtualenv
 ENV PYTHONUSERBASE /venv
 RUN mkdir /venv \
-  && pip3 install --ignore-installed --user -U pyopenssl cryptography certifi idna ndg-httpsclient pyasn1 \
+  && cd /src \
   && pip3 install --ignore-installed --user -r /src/requirements.txt
 
-# Copy the source code into the container
-COPY . /src
-
 ################################################################################################################
 
 FROM python:3.7-stretch as app
@@ -23,6 +25,8 @@ ENV PYTHONPATH /:/venv/lib/python3.7/site-packages
 ENV PATH $PATH:/venv/bin
 ENV FLASK_APP karrot.wsgi
 ENV FLASK_ENV production
+ENV AWS_DEFAULT_REGION us-east-1
+
 # Copy the app src and dependencies
 COPY --from=0 /src /app
 COPY --from=0 /venv /venv
@@ -32,4 +36,4 @@ WORKDIR /app
 EXPOSE 5000
 
 ENTRYPOINT ["/entrypoint.sh"]
-CMD ["karrot:create_app()", "--bind 127.0.0.1:5000", "-w 4"]
+CMD ["karrot:create_app()", "--bind :5000", "-w 4"]

Makefile

@@ -1,14 +1,49 @@
-.PHONY: run gunicorn
+.PHONY: dev tests lint checkstyle coverage docs run gunicorn docker
 SHELL := /bin/bash
 
+docker:
+	docker build . -t lowess/karrot
+
+docker-run:
+	docker run -it --rm \
+	--name karrot \
+	-p 5000:5000 \
+	lowess/karrot
+
+dev:
+	@echo ⚙️ Setting up dev environment and dependencies...
+	pip install -r dev/requirements.txt
+
+tests:
+	$(MAKE) lint
+	$(MAKE) checkstyle
+	$(MAKE) coverage
+
+lint:
+	@echo 💠 Linting code...
+	tox -e lint
+
+checkstyle:
+	@echo ✅ Validating checkstyle...
+	tox -e checkstyle
+
+coverage:
+	@echo 🔍️  Run test coverage...
+	tox -e coverage
+
+docs:
+	@echo 📚 Generate documentation using sphinx...
+	$(MAKE) -C ./docs/sphinx html
 
 run:
+	@echo 🚀 Run development server...
 	export prometheus_multiproc_dir=.prom; \
 	export FLASK_APP=karrot; \
 	export FLASK_ENV=dev; \
 	flask run
 
 gunicorn:
+	@echo 🚀 Run production gunicorn...
 	export prometheus_multiproc_dir=.prom; \
 	export FLASK_APP=karrot.wsgi; \
 	export FLASK_ENV=prod; \

README.md

@@ -1,4 +1,8 @@
 [![Build Status](https://cloud.drone.io/api/badges/Lowess/karrot/status.svg)](https://cloud.drone.io/Lowess/karrot)
+[![Coverage Status](https://coveralls.io/repos/github/Lowess/karrot/badge.svg?branch=master)](https://coveralls.io/github/Lowess/karrot?branch=master)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-black.svg)](https://github.com/psf/black)
+[![Linter: flake8](https://img.shields.io/badge/linter-flake8-blue.svg)](http://flake8.pycqa.org/en/latest/)
+[![Linter: tests](https://img.shields.io/badge/tests-tox-yellow.svg)](hhttps://tox.readthedocs.io/en/latest)
 
 # :carrot: Karrot - A Kafka lag reporter processing events from Burrow
 
@@ -84,12 +88,6 @@ flask "karrot:create_app()" --bind 127.0.0.1:5000 -w 4
 
 ## Reporter specific env vars:
 
-* Prometheus
-
-| env                               | value     | description                                        |
-|-----------------------------------|-----------|----------------------------------------------------|
-| `KARROT_PROMETHEUS_METRIC_PREFIX` | `karrot_` | Prefix name to use for exported prometheus metrics |
-
 * Cloudwatch
 
 | env                           | value                             | description                                                             |
@@ -100,7 +98,53 @@ flask "karrot:create_app()" --bind 127.0.0.1:5000 -w 4
 ---
 
 # :wrench: Developer Guide
-* Running a Kafka / Zk / Burrow / Karrot stack locally
+
+## TL;DR
+
+```bash
+# Install development requirements
+make dev
+
+# Setup pre-commit hook locally
+pre-commit install
+
+# Run full tests
+make tests
+
+# Build Sphinx documentation locally
+make docs
+```
+
+## IDE configuration
+
+* VSCode `settings.json`
+
+```json
+{
+  "python.linting.pylintEnabled": false,
+  "python.linting.flake8Enabled": true,
+  "python.linting.enabled": true,
+  "python.formatting.provider": "black",
+  "python.pythonPath": "~/.pyenv/versions/konnector/bin/python",
+  "python.venvPath": "~/.pyenv/shims",
+  "editor.formatOnPaste": false,
+  "editor.formatOnSave": true
+}
+```
+
+## Formatting & Linters
+
+ The project uses [Flake8](http://flake8.pycqa.org/en/latest/) linter and [Black](https://black.readthedocs.io/en/latest/) autoformatter
+
+## Tests
+
+Tests are automated with [Tox](https://tox.readthedocs.io/en/latest/) and run with [Pytest](https://docs.pytest.org/en/latest/) suite. [Codecoverage](https://coverage.readthedocs.io/en/latest/) is also reported during test runs.
+
+## Documentation
+
+The documentation can be genered with [Sphinx](https://www.sphinx-doc.org/en/2.0/)
+
+## Running a Kafka / Zk / Burrow / Karrot stack locally
 
 ```bash
 # Start the stack locally using docker-compose

dev/requirements.txt

@@ -0,0 +1,2 @@
+# Check setup.py
+-e '.[dev]'

docs/requirements.txt

@@ -0,0 +1,2 @@
+# Check setup.py
+-e '.[docs]'