docs(readme) add more development instructions

The different test suites and the way test/development running Kong need
a different configuration file can be confusing at first, so this adds
some more insight as to what is needed and why.

Of course, this is the current system but nothing prevents it from being
improved in the future.

Makefile

@@ -2,7 +2,7 @@ TESTING_CONF = kong_TEST.yml
 DEVELOPMENT_CONF = kong_DEVELOPMENT.yml
 DEV_ROCKS=busted luacov luacov-coveralls luacheck
 
-.PHONY: install dev clean start restart seed drop lint test test-integration test-plugins test-all coverage
+.PHONY: install dev doc clean start restart seed drop lint test test-integration test-plugins test-all coverage
 
 install:
 	@if [ `uname` = "Darwin" ]; then \
@@ -47,6 +47,9 @@ seed:
 drop:
 	@bin/kong db -c $(DEVELOPMENT_CONF) drop
 
+doc:
+	@ldoc -c config.ld kong
+
 lint:
 	@find kong spec -name '*.lua' -not -name 'invalid-module.lua' -not -path 'kong/vendor/*' | xargs luacheck -q
 

README.md

@@ -112,7 +112,6 @@ Tools:
 - [Kong with Instaclustr](https://www.instaclustr.com/products/kong/)
 - [.NET Client for Kong](https://www.nuget.org/packages/Kong/0.0.4)
 
-
 ## Roadmap
 
 You can find a detailed Roadmap of Kong on the [Wiki](https://github.com/Mashape/kong/wiki).
@@ -132,26 +131,104 @@ You can use a Vagrant box running Kong and Cassandra that you can find at [Masha
 First, you will need to already have Kong installed. Install Kong by following one of the methods described at [getkong.org/download](http://getkong.org/download). Then, make sure you have downloaded [Cassandra](http://cassandra.apache.org/download/) and that it is running. These steps will override your Kong installation with the latest source code:
 
 ```shell
-# clone the repo and use the next branch
 $ git clone https://github.com/Mashape/kong
 $ cd kong/
+
+# You might want to switch to the development branch. See CONTRIBUTING.md for more infos
 $ git checkout next
 
-# Build and install Kong globally using Luarocks, overriding the version previously installed
-$ [sudo] make install
+# Install latest Kong globally using Luarocks, overriding the version previously installed
+$ make install
+```
+
+#### Running for development
+
+It is best to run Kong with a development configuration file. Such a file can easily be created following those instructions:
 
+```shell
 # Install all development dependencies and create your environment configuration files
 $ make dev
 
 # Finally, run Kong with the just created development configuration
 $ kong start -c kong_DEVELOPMENT.yml
 ```
 
-The `lua_package_path` directive in the configuration specifies that the Lua code in your local folder will be used in favor of the system installation. The `lua_code_cache` directive being turned off, you can start Kong, edit your local files, and test your code without restarting Kong.
+Since you use a configuration file dedicated to development, feel free to customize it as you wish. For example, the one generated by `make dev` includes the following changes: the [`lua_package_path`](https://github.com/openresty/lua-nginx-module#lua_package_path) directive specifies that the Lua modules in your current directory will be used in favor of the system installation. The [`lua_code_cache`](https://github.com/openresty/lua-nginx-module#lua_code_cache) directive being turned off, you can start Kong, edit your local files, and test your code without restarting Kong.
+
+To stop Kong, you will need to specify the configuration file too:
+
+```shell
+$ kong stop -c kong_DEVELOPMENT.yml
+# or
+$ kong reload -c kong_DEVELOPMENT.yml
+```
+
+Learn more about the CLI and configuration options in the [documentation](https://getkong.org/docs/latest/cli/).
+
+#### Tests
+
+Kong relies on three test suites:
+
+* Unit tests
+* Integration tests, which require a running Cassandra cluster
+* Plugins tests, which are a mix of unit and integration tests, which also require a Cassandra cluster
+
+The first can simply be run after installing [busted](https://github.com/Olivine-Labs/busted) and running:
+
+```
+$ busted spec/unit
+```
+
+The integration tests require you to have a configuration file at `./kong_TEST.yml` and to make it point to a running Cassandra cluster (it will use a keyspace of its own). Such a file is also created by `make dev`, but you can create one of your own or customize it (you might want to change the logging settings, for example):
+
+```
+$ busted spec/integration
+```
+
+The `make dev` command can create a default `kong_TEST.yml` file.
+
+The plugins tests also require a `./kong_TEST.yml` file and a running Cassandra cluster, and be be run with:
+
+```
+$ busted spec/plugins
+```
+
+Finally, all suites can be run at once by simply running `busted`.
+
+#### Tools
+
+Various tools are used for documentation and code quality. They can all be easily installed by running:
+
+```
+$ make dev
+```
+
+Code coverage is analyzed by [luacov](http://keplerproject.github.io/luacov/) from the busted **unit tests**:
+
+```
+$ busted --coverage
+$ luacov kong
+# or
+$ make coverage
+```
+
+The code is statically analyzed and linted by [luacheck](https://github.com/mpeterv/luacheck). It is easier to use the Makefile to run it:
+
+```
+$ make lint
+```
+
+The documentation is written according to the [ldoc](https://github.com/stevedonovan/LDoc) format and can be generated with:
+
+```
+$ ldoc -c config.ld kong/
+# or
+$ make doc
+```
 
 #### Makefile Operations
 
-When developing, use the `Makefile` for doing the following operations:
+When developing, you can use the `Makefile` for doing the following operations:
 
 | Name          | Description                                                              |
 | -------------:| -------------------------------------------------------------------------|