go/src/cmd/godoc

Copyright 2011 The Go Authors. All rights reserved.
Use of this source code is governed by a BSD-style
license that can be found in the LICENSE file.

godoc on appengine
------------------

Prerequisites
-------------

* Go appengine SDK 1.5.5 - 2011-10-11
  http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go

* Go sources at tip under $GOROOT


Directory structure
-------------------

* Let $APPDIR be the directory containing the app engine files.
  (e.g., $APPDIR=$HOME/godoc-app)

* $APPDIR contains the following entries (this may change depending on
  app-engine release and version of godoc):

	alt/
		encoding/binary/
		go/*
		index/suffixarray/
	app.yaml
	godoc.zip
	godoc/
	index.split.*

* The app.yaml file is set up per app engine documentation.
  For instance:

	application: godoc-app
	version: 1-5-5
	runtime: go
	api_version: 3

	handlers:
	- url: /.*
	  script: _go_app

* The godoc/ directory contains a copy of the files under $GOROOT/src/cmd/godoc
  with modifications:

	- doc.go is excluded (it belongs to pseudo-package ÒdocumentationÓ)
	- main.go is excluded (appinit.go is taking its place)

  Additional manual modifications are required to refer to the alt/ packages
  where the app-engine library is not up-to-date with the godoc version.

* The alt/ directory contains up-to-date copies of Go packages that a tip-based
  godoc is dependent on but which do not yet exist in the current app-engine SDK.
  At the time of this writing (10/14/2011) this is the entire go directory tree
  (for the missing FileSet serialization code in go/token) as well as the
  index/suffixarray package (for the missing suffix array serialization code).
  The latest (alt/)index/suffixarray package internally requires the latest
  version of encoding/binary, which is why it also needs to be present under
  alt/.


Configuring and running godoc
-----------------------------

To configure godoc, run

	bash setup-godoc-app.bash

to create the godoc.zip, index.split.*, and godoc/appconfig.go files
based on $GOROOT and $APPDIR. See the script for details on usage.

To run godoc locally, using the app-engine emulator, run

	<path to google_appengine>/dev_appserver.py $APPDIR

godoc should come up at http://localhost:8080 .