content: update README

The README does not mention that files that are newly added to
the content directory need to be added manually to static/gen.go
file before running go generate. This change fixes that.

Update the description of how the static content is used in concert
with the content from the main Go repository in more detail.

Replace go install && ./golangorg with go run, since it's shorter.

Add a TODO note mentioning improvements that can be made in the near
future to simplify this process.

Updates golang/go#29206

Change-Id: I8a85bcb783c7c10975aa6fd5a7ad464f05d42dd2
Reviewed-on: https://go-review.googlesource.com/c/website/+/207262
Reviewed-by: Andrew Bonventre <[email protected]>

Author: dmitshur

content/README.md

@@ -1,11 +1,17 @@
 # content
 
-This directory contains doc/, static/, favicon.ico, and robots.txt. The
-executable lives at golang.org/x/website/cmd/golangorg.
+The `static` directory contains static content. This content is used alongside
+the content in the main Go repository by the [`golangorg`](golang.org/x/website/cmd/golangorg)
+binary when serving the [golang.org](https://golang.org) website.
+The details of the directory to path mapping are documented at the top of
+[`cmd/golangorg/main.go`](https://go.googlesource.com/website/+/refs/heads/master/cmd/golangorg/main.go).
+
+TODO(dmitshur): The process below can be simplified.
+See [golang.org/issue/29206#issuecomment-536099768](https://golang.org/issue/29206#issuecomment-536099768).
 
 ## Development mode
 
-In production, CSS/JS/template assets need to be compiled into the golangorg
+In production, CSS/JS/template assets need to be compiled into the `golangorg`
 binary. It can be tedious to recompile assets every time, but you can pass a
 flag to load CSS/JS/templates from disk every time a page loads:
 
@@ -15,16 +21,31 @@ golangorg -templates=$GOPATH/src/golang.org/x/website/content/static -http=:6060
 
 ## Recompiling static assets
 
-The files that live at `static/style.css`, `static/jquery.js` and so on are not
-present in the final binary. They are placed into `static/static.go` by running
-`go generate`. So to compile a change and test it in your browser:
+Files such as `static/style.css`, `static/doc/copyright.html` and so on are not
+present in the final binary. They are embedded into `static/static.go` by running
+`go generate`. To compile a change and test it in your browser:
+
+1) Make changes to an existing file such as `static/style.css`.
+
+2) If a new file is being added to the `static` directory, add it to the `files`
+slice in `static/gen`.
 
-1) Make changes to e.g. `static/style.css`.
+3) Run `go generate golang.org/x/website/content/static` so `static/static.go` is
+up to date.
 
-2) Run `go generate golang.org/x/website/content/static` so `static/static.go` picks
-up the change.
+4) Run `go run golang.org/x/website/cmd/golangorg -http=:6060` and view your changes
+in the browser at http://localhost:6060. You may need to disable your browser's cache
+to avoid reloading a stale file.
 
-3) Run `go install golang.org/x/website/cmd/golangorg` so the compiled `golangorg` binary picks up the change.
+A test exists to catch a possible mistake of forgetting to regenerate static assets:
 
-4) Run `golangorg -http=:6060` and view your changes in the browser. You may need
-to disable your browser's cache to avoid reloading a stale file.
+```
+website $ go test ./...
+--- FAIL: TestStaticIsUpToDate (0.06s)
+    gen_test.go:27: static.go is stale.  Run:
+          $ go generate golang.org/x/website/content/static
+          $ git diff
+        to see the differences.
+FAIL
+FAIL	golang.org/x/website/content/static	0.650s
+```