From cb538dbcf8433b41e56e07ccae2256c5632c555c Mon Sep 17 00:00:00 2001 From: Kevin Burke Date: Sat, 7 Jan 2017 15:09:41 -0800 Subject: [PATCH] godoc: add README Explain how to make changes to the project's static files and get them compiled in to the godoc binary. Change-Id: I12e0c50bf31925b3f211b6d0dd3e5f8cff547f32 Reviewed-on: https://go-review.googlesource.com/34925 Reviewed-by: Brad Fitzpatrick --- cmd/godoc/main.go | 2 +- godoc/README.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 godoc/README.md diff --git a/cmd/godoc/main.go b/cmd/godoc/main.go index 6414194a53..60cedf859f 100644 --- a/cmd/godoc/main.go +++ b/cmd/godoc/main.go @@ -89,7 +89,7 @@ var ( // layout control tabWidth = flag.Int("tabwidth", 4, "tab width") showTimestamps = flag.Bool("timestamps", false, "show timestamps with directory listings") - templateDir = flag.String("templates", "", "directory containing alternate template files") + templateDir = flag.String("templates", "", "load templates/JS/CSS from disk in this directory") showPlayground = flag.Bool("play", false, "enable playground in web interface") showExamples = flag.Bool("ex", false, "show examples in command line mode") declLinks = flag.Bool("links", true, "link identifiers to their declarations") diff --git a/godoc/README.md b/godoc/README.md new file mode 100644 index 0000000000..1c495c8d64 --- /dev/null +++ b/godoc/README.md @@ -0,0 +1,31 @@ +# godoc + +This directory contains most of the code for running a godoc server. The +executable lives at golang.org/x/tools/cmd/godoc. + +## Development mode + +In production, CSS/JS/template assets need to be compiled into the godoc +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: + +``` +godoc --templates=$GOPATH/src/golang.org/x/tools/godoc/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: + +1) Make changes to e.g. `static/style.css`. + +2) Run `go generate golang.org/x/tools/godoc/static` so `static/static.go` picks +up the change. + +3) Run `go install golang.org/x/tools/cmd/godoc` so the compiled `godoc` binary +picks up the change. + +4) Run `godoc -http=:6060` and view your changes in the browser. You may need +to disable your browser's cache to avoid reloading a stale file.