Merge pull request #204 from coreos/update-dev-documentation

Tweak dev guide & update example README

Documentation/dev-guide.md

@@ -2,13 +2,25 @@
 
 ## No DB mode
 
-When you are working on dex it's convenient to use the "--no-db" flag, which starts up Dex in a mode which uses an in-memory datastore for persistence. It also does not rotate keys, so no overlord is required.
+When you are working on dex it's convenient to use the `--no-db` flag. This starts up dex in a mode which uses an in-memory datastore for persistence. It also does not rotate keys, so no overlord is required.
 
-In this mode you provide the binary with paths to files to connectors and users - there are example files you can use inside of `static/fixtures`, named "connectors.json.sample" and "users.json.sample" respectively. If you rename these to the equivalent without the ".sample", the defaults point to this location, making starting dex as simple as:
+In this mode you provide the binary with paths to files for connectors, users, and emailer. There are example files you can use inside of `static/fixtures` named *"connectors.json.sample"*, *"users.json.sample"*, and *"emailer.json.sample"*, respectively.
 
-`./bin/dex-worker  --no-db`
+You can rename these to the equivalent without the *".sample"* suffix since the defaults point to those locations:
 
-*Do not use this flag in production* - it's not thread safe and data is destroyed when the process dies. In addition, there is no key rotation.
+```console
+mv static/fixtures/connectors.json.sample static/fixtures/connectors.json
+mv static/fixtures/users.json.sample static/fixtures/users.json
+mv static/fixtures/emailer.json.sample static/fixtures/emailer.json
+```
+
+Starting dex is then as simple as:
+
+```console
+bin/dex-worker  --no-db
+```
+
+***Do not use this flag in production*** - it's not thread safe and data is destroyed when the process dies. In addition, there is no key rotation.
 
 Note: If you want to test out the registration flow, you need to enable that feature by passing `--enable-registration=true` as well.
 
@@ -22,7 +34,7 @@ You can also use a copy of `go` hosted inside a Docker container if you prefix y
 
 Once binaries are compiled you can build and push a dex image to quay.io. Before doing this step binaries must be built above using one of the build tools.
 
-```
+```console
 export DOCKER_USER=<<your user>>
 export DOCKER_PASSWORD=<<your password>>
 ./build-docker-push
@@ -35,15 +47,15 @@ By default the script pushes to `quay.io/coreos/dex`; if you want to push to a d
 Go API bindings are generated from a JSON Discovery file.
 To regenerate run:
 
-```
-./schema/generator
+```console
+schema/generator
 ```
 
 For updating generator dependencies see docs in: `schema/generator_import.go`.
 
 ## Running Tests
 
-To run all tests (except functional) use the `./test` script; 
+To run all tests (except functional) use the `./test` script;
 
 If you want to test a single package only, use `PKG=<pkgname> ./test`
 
@@ -52,7 +64,7 @@ The functional tests require a database; create a database (eg. `createdb dex_fu
 To run these tests with Docker is a little trickier; you need to have a container running Postgres, and then you need to link that container to the container running your tests:
 
 
-```
+```console
 # Run the Postgres docker container, which creates a db called "postgres"
 docker run --name dex_postgres -d postgres
 
@@ -67,4 +79,3 @@ DOCKER_LINKS=dex_postgres:postgres DOCKER_ENV=DEX_TEST_DSN ./go-docker ./test-fu
 # Remove the container after the tests are run.
 rm -f dex_postgres
 ```
-

examples/README.md

@@ -6,14 +6,14 @@ The quickest way to start experimenting with dex is to run a single dex-worker l
 
 First, build the example webapp client and example CLI client.
 
-```
+```console
 ./build
 ```
 
 Now copy the example configurations into place to get dex configured.
 You can customize these later but the defaults should work fine.
 
-```
+```console
 cp static/fixtures/connectors.json.sample static/fixtures/connectors.json
 cp static/fixtures/users.json.sample static/fixtures/users.json
 cp static/fixtures/emailer.json.sample static/fixtures/emailer.json
@@ -21,7 +21,7 @@ cp static/fixtures/emailer.json.sample static/fixtures/emailer.json
 
 With `dex-worker` configuration in place we can start dex in local mode.
 
-```
+```console
 ./bin/dex-worker --no-db &
 ```
 
@@ -30,7 +30,7 @@ With `dex-worker` configuration in place we can start dex in local mode.
 Build and run the example app webserver by pointing the discovery URL to local Dex, and 
 supplying the client information from `./static/fixtures/clients.json` into the flags.
 
-```
+```console
 ./bin/example-app \
 	--client-id=example-app \
 	--client-secret=example-app-secret \
@@ -38,12 +38,10 @@ supplying the client information from `./static/fixtures/clients.json` into the
 ```
 
 Visit [http://localhost:5555](http://localhost:5555) in your browser and click "login" link.
-Next click "Login with Local" and enter the sample credentials from `static/fixtures/connectors.json`:
+Next click "Login with Email" and enter the sample credentials from `static/fixtures/connectors.json`:
 
-```
-email: elroy77@example.com
-password: bones
-```
+* email: `elroy77@example.com`
+* password: `bones`
 
 The example app will dump out details of the JWT issued by Dex which means that authentication was successful and the application has authenticated you as a valid user.
 You can play with adding additional users in connectors.json and users.json.
@@ -52,7 +50,7 @@ You can play with adding additional users in connectors.json and users.json.
 
 The example CLI will start, connect to the Dex instance to gather discovery information, listen on `localhost:8000`, and then acquire a client credentials JWT and print it out.
 
-```
+```console
 ./bin/example-cli \
 	--client-id example-cli
 	--client-secret examplie-cli-secret