From fd4520205a792ee1aad1e283352ab3bc42a5f922 Mon Sep 17 00:00:00 2001 From: Dmitri Shuralyov Date: Thu, 14 Nov 2019 18:42:10 +0000 Subject: [PATCH] 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 --- content/README.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/content/README.md b/content/README.md index 692f5eb8c0..05cd1bea8b 100644 --- a/content/README.md +++ b/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 +```