WIP: Re-work README to make it clearer how to run the app

App dependency install, build script and startup scripts seemed
oddly dispersed throughout the README, making it difficult to
talk about shared logic such as the ENV variables. I've consolidated
these into their own "Run the app locally" section.

Other things to note:

- I added `--verbose` to the build script, as the build initially
  failed for me and I had to re-run the script with verbose mode
  to see any meaningful output. The output isn't much more verbose
  than without the flag, so there seems no downside.
- I removed the section on `.env` file, as it seems to be an
  implementation detail, and also incompatible with running via
  govuk-docker. But I'd like to revisit this.
- I'm currently able to compile the website fine, and fetch the
  remote docs, but am struggling to get the app to _run_ locally
  (in govuk-docker).
- I'd very much like to remove the "docker-compose.yml" hack
  workaround.

Author: ChrisBAshton

README.md

@@ -7,43 +7,39 @@ This is a static site generated with Middleman, using [alphagov/tech-docs-templa
 Some of the files (like the CSS, javascripts and layouts) are managed in the template and are not supposed to be modified here. Any project-specific
 Ruby code needs to go into `/app`.
 
-## Build the app locally
+## Run the app locally
+
+Install the dependencies:
 
 ```sh
 bundle install
 ```
 
-## Run the tests locally
+You can then start up the site with `./startup.sh` (or `govuk-docker-up` if using [govuk-docker](https://github.com/alphagov/govuk-docker)). The startup script can optionally be configured with the following ENV variables:
 
-```
-bundle exec rake
-```
+- `GOVUK_TOKEN=<your private token>` - token to use to make authenticated requests to GitHub's API. Authenticated requests have a much higher rate limit. *You will need to specify a `GITHUB_TOKEN` if you want to build the entire Developer Docs site*. You can [create a GitHub token](https://github.com/settings/tokens/new) (the token doesn't need any scopes).
+- `SKIP_PROXY_PAGES=true` - avoid fetching remote 'docs/' for each repo (i.e. just build the docs that live within govuk-developer-docs itself). You can use this if you don't have a `GITHUB_TOKEN` or if you don't care about including the remote docs.
 
-## Run the app locally
+If using govuk-docker, you may struggle to pass ENV variables to the script. You can work around this by [editing the docker-compose.yml](https://github.com/alphagov/govuk-docker/blob/ed98d3547708286f534598c78fb5c57ee3c8d112/projects/govuk-developer-docs/docker-compose.yml#L12) to add the following to the `govuk-developer-docs-lite` entry:
 
-```sh
-SKIP_PROXY_PAGES=true ./startup.sh
+```yml
+   environment:
+      LANG: "C.UTF-8"
+      GITHUB_TOKEN: "<fill it in>"
+      NO_CONTRACTS: true
 ```
 
-## Proxy pages
-
-The live docs site includes pages from other alphagov GitHub repositories. To test this locally, omit `SKIP_PROXY_PAGES=true` from the command above.
-
-The app downloads these "proxy pages" at startup and this can cause GitHub to rate limit your requests. You can pass a valid GitHub API token to the app to help avoid this:
-
-1. [Create a GitHub token](https://github.com/settings/tokens/new). The token doesn't need any scopes.
-
-1. Store the token in a `.env` file:
+If you just want to create the site (a `build/` directory containing a set of HTML files), but not actyally start up the application, you can do so as follows (noting that the ENV variables described above apply here too):
 
-    ```sh
-    GITHUB_TOKEN=somethingsomething
-    ```
+```sh
+NO_CONTRACTS=true bundle exec middleman build --verbose
+```
 
-1. Start the application:
+## Run the tests locally
 
-    ```sh
-    ./startup.sh
-    ```
+```
+bundle exec rake
+```
 
 ## Update to the latest Tech Docs template
 
@@ -58,14 +54,6 @@ We host GOV.UK Developer Docs as a static site on GitHub Pages. The [ci.yml] Git
 - when a PR is merged to the default branch
 - on an hourly schedule, to pick up changes to docs included from other repos
 
-### Build the static site locally
-
-```sh
-NO_CONTRACTS=true bundle exec middleman build
-```
-
-This will create a `build` directory containing a set of HTML files.
-
 ## Licence
 
 [MIT License](LICENCE)