update docs

Author: collerek

docs/contributing.md

@@ -0,0 +1,83 @@
+# Contibuting
+
+All contributions to *databases* are welcomed!
+
+## Issues
+
+To make it as simple as possible for us to help you, please include the following:
+
+* OS 
+* python version
+* databases version
+* database backend (mysql, sqlite or postgresql)
+* database driver (aiopg, aiomysql etc.)
+
+Please try to always include the above unless you're unable to install *databases* or **know** it's not relevant
+to your question or feature request.
+
+## Pull Requests
+
+It should be quite straight forward to get started and create a Pull Request.
+
+!!! note
+    Unless your change is trivial (typo, docs tweak etc.), please create an issue to discuss the change before
+    creating a pull request.
+
+To make contributing as easy and fast as possible, you'll want to run tests and linting locally. 
+
+You'll need to have **python >= 3.6 (recommended 3.7+)** and **git** installed.
+
+## Getting started
+
+1. Clone your fork and cd into the repo directory
+```bash
+git clone [email protected]:<your username>/databases.git
+cd databases
+```
+
+2. Create and activate virtual env
+```bash
+virtualenv -p `which python3.6` env
+source env/bin/activate
+```
+
+3. Install databases, dependencies and test dependencies
+```bash
+pip install -r requirements.txt
+```
+
+4. Checkout a new branch and make your changes
+```bash
+git checkout -b my-new-feature-branch
+```
+
+## Make your changes...
+
+## Contribute
+
+1. Formatting and linting - databases uses black for formatting, autoflake for linting and mypy for type hints check
+run all of those with lint script
+```bash
+./scripts/lint
+```
+
+2. Prepare tests (basic)
+   1. Set-up `TEST_DATABASE_URLS` env variable where you can comma separate urls for several backends
+   2. The simples one is for sqlite alone: `sqlite:///test.db`
+
+3. Prepare tests (all backends)
+   1. In order to run all backends you need a docker instalation on your system [from here](https://docs.docker.com/get-docker/)
+   2. You need to set-up `TEST_IN_DOCKER` env variable (to any non-null value `YES` or `1`)
+
+4. Run tests
+```bash
+./scripts/test
+```
+
+5. Build documentation
+   1. If you have changed the documentation make sure it runs successfully
+```bash
+./scripts/test
+```
+
+6. Commit, push, and create your pull request

mkdocs.yml

@@ -13,6 +13,7 @@ nav:
     - Database Queries: 'database_queries.md'
     - Connections & Transactions: 'connections_and_transactions.md'
     - Tests & Migrations: 'tests_and_migrations.md'
+    - Contributing: 'contributing.md'
 
 markdown_extensions:
   - mkautodoc

scripts/docs

@@ -1,8 +1,21 @@
 #!/bin/sh -e
 
 export PREFIX=""
-if [ -d 'venv' ] ; then
+UNAME=$(uname)
+case "$UNAME" in
+"Linux") export SYSTEM="Linux" ;;
+"Darwin") export SYSTEM="Linux" ;;
+CYGWIN*) export SYSTEM="Windows" ;;
+MINGW*) export SYSTEM="Windows" ;;
+*) export SYSTEM="Linux" ;;
+esac
+
+if [ -d 'venv' ]; then
+  if [ $SYSTEM = "Linux" ] ; then
     export PREFIX="venv/bin/"
+  else
+    export PREFIX="venv/Scripts/"
+  fi
 fi
 
 set -x

scripts/test

@@ -18,8 +18,8 @@ if [ -d 'venv' ]; then
   fi
 fi
 
-if [ -z "$TEST_DATABASE_URLS" ]; then
-  echo "Variable TEST_DATABASE_URLS must be set."
+if [ -z "$TEST_DATABASE_URLS" ] && [ -z "${TEST_IN_DOCKER+x}" ]; then
+  echo "Variable TEST_DATABASE_URLS or TEST_IN_DOCKER must be set."
   exit 1
 fi
 

tests/test_databases.py

@@ -12,7 +12,9 @@
 
 from databases import Database, DatabaseURL
 
-if sys.version_info >= (3, 8) and sys.platform.lower().startswith("win"):
+if sys.version_info >= (3, 8) and sys.platform.lower().startswith(
+    "win"
+):  # pragma: no cover
     asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
 
 assert "TEST_DATABASE_URLS" in os.environ, "TEST_DATABASE_URLS is not set."