Problem: acceptance-test suite is not documented (#2267)

* Problem: acceptance-test suite is not documented

Solution: add README.md in the root of the acceptance tests, unify
`Makefile` and commands, remove more cached files when `make clean` is
ran.

* Problem: documentation does not mention Makefile

Solution: update docs with our new and shiny commands

Makefile

@@ -1,4 +1,4 @@
-.PHONY: check-deps help run test test-all coverage clean clean-build clean-pyc clean-test docs servedocs release dist install
+.PHONY: help run start stop logs test test-unit test-unit-watch test-acceptance cov doc doc-acceptance clean reset release dist check-deps clean-build clean-pyc clean-test
 
 .DEFAULT_GOAL := help
 
@@ -67,29 +67,31 @@ stop: check-deps ## Stop BigchainDB
 logs: check-deps ## Attach to the logs
 	@$(DC) logs -f bigchaindb
 
-test: check-deps ## Run all tests once
+test: check-deps test-unit test-acceptance ## Run unit and acceptance tests
+
+test-unit: check-deps ## Run all tests once
 	@$(DC) up -d bdb
 	@$(DC) exec bigchaindb pytest
 
-test-watch: check-deps ## Run all tests and wait. Every time you change code, tests will be run again
+test-unit-watch: check-deps ## Run all tests and wait. Every time you change code, tests will be run again
 	@$(DC) run --rm --no-deps bigchaindb pytest -f
 
-acceptance-test: check-deps ## Run all acceptance tests
+test-acceptance: check-deps ## Run all acceptance tests
 	@./run-acceptance-test.sh
 
-acceptance-test-doc: check-deps ## Create documentation for acceptance tests
-	@$(DC) run --rm python-acceptance pycco -i -s /src -d /docs
-	$(BROWSER) acceptance/python/docs/index.html
-
 cov: check-deps ## Check code coverage and open the result in the browser
 	@$(DC) run --rm bigchaindb pytest -v --cov=bigchaindb --cov-report html
 	$(BROWSER) htmlcov/index.html
 
-doc: ## Generate HTML documentation and open it in the browser
+doc: check-deps ## Generate HTML documentation and open it in the browser
 	@$(DC) run --rm --no-deps bdocs make -C docs/root html
 	@$(DC) run --rm --no-deps bdocs make -C docs/server html
 	$(BROWSER) docs/root/build/html/index.html
 
+doc-acceptance: check-deps ## Create documentation for acceptance tests
+	@$(DC) run --rm python-acceptance pycco -i -s /src -d /docs
+	$(BROWSER) acceptance/python/docs/index.html
+
 clean: clean-build clean-pyc clean-test ## Remove all build, test, coverage and Python artifacts
 	@$(ECHO) "Cleaning was successful."
 
@@ -132,6 +134,7 @@ clean-pyc: # Remove Python file artifacts
 	@find . -name '__pycache__' -exec rm -fr {} +
 
 clean-test: # Remove test and coverage artifacts
+	@find . -name '.pytest_cache' -exec rm -fr {} +
 	@rm -fr .tox/
 	@rm -f .coverage
 	@rm -fr htmlcov/

README.md

@@ -26,8 +26,8 @@ There are also other commands you can execute:
 - `make start`: Run BigchainDB from source and daemonize it (stop it with `make stop`).
 - `make stop`: Stop BigchainDB.
 - `make logs`: Attach to the logs.
-- `make test`: Run all tests.
-- `make test-watch`: Run all tests and wait. Every time you change code, tests will be run again.
+- `make test`: Run all unit and acceptance tests.
+- `make test-unit-watch`: Run all tests and wait. Every time you change code, tests will be run again.
 - `make cov`: Check code coverage and open the result in the browser.
 - `make doc`: Generate HTML documentation and open it in the browser.
 - `make clean`: Remove all build, test, coverage and Python artifacts.

acceptance/README.md

@@ -0,0 +1,20 @@
+# Acceptance test suite
+This directory contains the acceptance test suite for BigchainDB.
+
+The suite uses Docker Compose to set up a single BigchainDB node, run all tests, and finally stop the node. In the future we will add support for a four node network setup.
+
+## Running the tests
+It should be as easy as `make test-acceptance`.
+
+Note that `make test-acceptance` will take some time to start the node and shutting it down. If you are developing a test, or you wish to run a specific test in the acceptance test suite, first start the node with `make start`. After the node is running, you can run `pytest` inside the `python-acceptance` container with:
+
+```bash
+docker-compose run --rm python-acceptance pytest <use whatever option you need>
+```
+
+## Writing and documenting the tests
+Tests are sometimes difficult to read. For acceptance tests, we try to be really explicit on what the test is doing, so please write code that is *simple* and easy to understand. We decided to use literate-programming documentation. To generate the documentation run:
+
+```bash
+make doc-acceptance
+```

docs/contributing/source/dev-setup-coding-and-contribution-process/run-node-with-docker-compose.md

@@ -2,6 +2,29 @@
 
 ## Setting up a single node development environment with ``docker-compose``
 
+### Using the BigchainDB 2.0 developer toolbox
+We grouped all useful commands under a simple `Makefile`.
+
+Run a BigchainDB node in the foreground:
+```bash
+$ make run
+```
+
+There are also other commands you can execute:
+- `make start`: Run BigchainDB from source and daemonize it (stop it with `make stop`).
+- `make stop`: Stop BigchainDB.
+- `make logs`: Attach to the logs.
+- `make test`: Run all unit and acceptance tests.
+- `make test-unit-watch`: Run all tests and wait. Every time you change code, tests will be run again.
+- `make cov`: Check code coverage and open the result in the browser.
+- `make doc`: Generate HTML documentation and open it in the browser.
+- `make clean`: Remove all build, test, coverage and Python artifacts.
+- `make reset`: Stop and REMOVE all containers. WARNING: you will LOSE all data stored in BigchainDB.
+
+
+### Using `docker-compose` directly
+The BigchainDB `Makefile` is a wrapper around some `docker-compose` commands we use frequently. If you need a finer granularity to manage the containers, you can still use `docker-compose` directly. This part of the documentation explains how to do that.
+
 ```bash
 $ docker-compose build bigchaindb
 $ docker-compose up -d bdb