Skip to content

Commit efeb149

Browse files
author
Jay Conrod
committed
cmd/golangorg, content: serve /doc from content/static/doc before GOROOT/doc
In the "/doc" directory, files are now served from the content/static/doc, then from GOROOT/doc (where GOROOT is either a zip file or the GOROOT directory). This allows documentation to be moved to golang.org outside of the normal Go release cycle. For example, this CL moves (but does not modify) doc/docs.html here. Documentation that is tied to the Go release cycle (for example, doc/spec.html) will not be moved. Updates golang/go#33637 Updates golang/go#29206 Change-Id: I5f1c577e0ffddc3418653bdd9b0cc36cf79e3fe1 Reviewed-on: https://go-review.googlesource.com/c/website/+/197638 Run-TryBot: Jay Conrod <[email protected]> TryBot-Result: Gobot Gobot <[email protected]> Reviewed-by: Dmitri Shuralyov <[email protected]>
1 parent 07c3481 commit efeb149

File tree

7 files changed

+256
-18
lines changed

7 files changed

+256
-18
lines changed

‎cmd/golangorg/appinit.go

+5-4
Original file line numberDiff line numberDiff line change
@@ -75,10 +75,11 @@ func main() {
7575
fs.Bind("/", rootfs, "/", vfs.BindReplace)
7676
}
7777

78-
// Use a local copy of root.html instead of the one in the main go repository.
79-
// See golang.org/issue/29206 for more info.
80-
fs.Bind("/doc/root.html", mapfs.New(static.Files), "/doc/root.html", vfs.BindReplace)
81-
fs.Bind("/doc/copyright.html", mapfs.New(static.Files), "/doc/copyright.html", vfs.BindReplace)
78+
// Try serving files in /doc from a local copy before trying the main
79+
// go repository. This lets us update some documentation outside the
80+
// Go release cycle. This includes root.html, which redirects to "/".
81+
// See golang.org/issue/29206.
82+
fs.Bind("/doc", mapfs.New(static.Files), "/doc", vfs.BindBefore)
8283
fs.Bind("/lib/godoc", mapfs.New(static.Files), "/", vfs.BindReplace)
8384

8485
webroot := getFullPath("/src/golang.org/x/website")

‎cmd/golangorg/main.go

+9-9
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,16 @@
77
// Web server tree:
88
//
99
// https://golang.org/ main landing page
10-
// https://golang.org/doc/ serve from $GOROOT/doc - spec, mem, etc.
10+
// https://golang.org/doc/ serve from content/static/doc, then $GOROOT/doc. spec, mem, etc.
1111
// https://golang.org/src/ serve files from $GOROOT/src; .go gets pretty-printed
1212
// https://golang.org/cmd/ serve documentation about commands
1313
// https://golang.org/pkg/ serve documentation about packages
1414
// (idea is if you say import "compress/zlib", you go to
1515
// https://golang.org/pkg/compress/zlib)
1616
//
1717

18-
// Some pages are being transitioned from $GOROOT to this source tree.
19-
// See bindings below to see which ones.
18+
// Some pages are being transitioned from $GOROOT to content/static/doc.
19+
// See golang.org/issue/29206 and golang.org/issue/33637.
2020

2121
// +build !golangorg
2222

@@ -143,15 +143,15 @@ func main() {
143143
defer rc.Close() // be nice (e.g., -writeIndex mode)
144144
fs.Bind("/", zipfs.New(rc, *zipfile), *goroot, vfs.BindReplace)
145145
}
146-
// Use a local copy of root.html instead of the one in the main go repository.
147-
// See golang.org/issue/29206 for more info.
146+
// Try serving files in /doc from a local copy before trying the main
147+
// go repository. This lets us update some documentation outside the
148+
// Go release cycle. This includes root.html, which redirects to "/".
149+
// See golang.org/issue/29206.
148150
if *templateDir != "" {
149-
fs.Bind("/doc/root.html", vfs.OS(*templateDir), "/doc/root.html", vfs.BindReplace)
150-
fs.Bind("/doc/copyright.html", vfs.OS(*templateDir), "/doc/copyright.html", vfs.BindReplace)
151+
fs.Bind("/doc", vfs.OS(*templateDir), "/doc", vfs.BindBefore)
151152
fs.Bind("/lib/godoc", vfs.OS(*templateDir), "/", vfs.BindBefore)
152153
} else {
153-
fs.Bind("/doc/root.html", mapfs.New(static.Files), "/doc/root.html", vfs.BindReplace)
154-
fs.Bind("/doc/copyright.html", mapfs.New(static.Files), "/doc/copyright.html", vfs.BindReplace)
154+
fs.Bind("/doc", mapfs.New(static.Files), "/doc", vfs.BindBefore)
155155
fs.Bind("/lib/godoc", mapfs.New(static.Files), "/", vfs.BindReplace)
156156
}
157157

‎content/static/doc/docs.html

+232
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
<!--{
2+
"Title": "Documentation",
3+
"Path": "/doc/",
4+
"Template": true
5+
}-->
6+
7+
<p>
8+
The Go programming language is an open source project to make programmers more
9+
productive.
10+
</p>
11+
12+
<p>
13+
Go is expressive, concise, clean, and efficient. Its concurrency
14+
mechanisms make it easy to write programs that get the most out of multicore
15+
and networked machines, while its novel type system enables flexible and
16+
modular program construction. Go compiles quickly to machine code yet has the
17+
convenience of garbage collection and the power of run-time reflection. It's a
18+
fast, statically typed, compiled language that feels like a dynamically typed,
19+
interpreted language.
20+
</p>
21+
22+
<div id="manual-nav"></div>
23+
24+
<h2>Installing Go</h2>
25+
26+
<h3><a href="/doc/install">Getting Started</a></h3>
27+
<p>
28+
Instructions for downloading and installing the Go compilers, tools, and
29+
libraries.
30+
</p>
31+
32+
33+
<h2 id="learning">Learning Go</h2>
34+
35+
<img class="gopher" src="/doc/gopher/doc.png"/>
36+
37+
<h3 id="go_tour">
38+
{{if $.GoogleCN}}
39+
A Tour of Go
40+
{{else}}
41+
<a href="//tour.golang.org/">A Tour of Go</a>
42+
{{end}}
43+
</h3>
44+
<p>
45+
An interactive introduction to Go in three sections.
46+
The first section covers basic syntax and data structures; the second discusses
47+
methods and interfaces; and the third introduces Go's concurrency primitives.
48+
Each section concludes with a few exercises so you can practice what you've
49+
learned. You can {{if not $.GoogleCN}}<a href="//tour.golang.org/">take the tour
50+
online</a> or{{end}} install it locally with:
51+
</p>
52+
<pre>
53+
$ go get golang.org/x/tour
54+
</pre>
55+
<p>
56+
This will place the <code>tour</code> binary in your workspace's <code>bin</code> directory.
57+
</p>
58+
59+
<h3 id="code"><a href="code.html">How to write Go code</a></h3>
60+
<p>
61+
{{if not $.GoogleCN}}
62+
Also available as a <a href="//www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>, this
63+
{{else}}
64+
This
65+
{{end}}
66+
doc explains how to use the <a href="/cmd/go/">go command</a>
67+
to fetch, build, and install packages, commands, and run tests.
68+
</p>
69+
70+
<h3 id="editors"><a href="editors.html">Editor plugins and IDEs</a></h3>
71+
<p>
72+
A document that summarizes commonly used editor plugins and IDEs with
73+
Go support.
74+
</p>
75+
76+
<h3 id="effective_go"><a href="effective_go.html">Effective Go</a></h3>
77+
<p>
78+
A document that gives tips for writing clear, idiomatic Go code.
79+
A must read for any new Go programmer. It augments the tour and
80+
the language specification, both of which should be read first.
81+
</p>
82+
83+
<h3 id="diagnostics"><a href="/doc/diagnostics.html">Diagnostics</a></h3>
84+
<p>
85+
Summarizes tools and methodologies to diagnose problems in Go programs.
86+
</p>
87+
88+
<h3 id="faq"><a href="/doc/faq">Frequently Asked Questions (FAQ)</a></h3>
89+
<p>
90+
Answers to common questions about Go.
91+
</p>
92+
93+
<h3 id="wiki"><a href="/wiki">The Go Wiki</a></h3>
94+
<p>A wiki maintained by the Go community.</p>
95+
96+
<h4 id="learn_more">More</h4>
97+
<p>
98+
See the <a href="/wiki/Learn">Learn</a> page at the <a href="/wiki">Wiki</a>
99+
for more Go learning resources.
100+
</p>
101+
102+
103+
<h2 id="references">References</h2>
104+
105+
<h3 id="pkg"><a href="/pkg/">Package Documentation</a></h3>
106+
<p>
107+
The documentation for the Go standard library.
108+
</p>
109+
110+
<h3 id="cmd"><a href="/doc/cmd">Command Documentation</a></h3>
111+
<p>
112+
The documentation for the Go tools.
113+
</p>
114+
115+
<h3 id="spec"><a href="/ref/spec">Language Specification</a></h3>
116+
<p>
117+
The official Go Language specification.
118+
</p>
119+
120+
<h3 id="go_mem"><a href="/ref/mem">The Go Memory Model</a></h3>
121+
<p>
122+
A document that specifies the conditions under which reads of a variable in
123+
one goroutine can be guaranteed to observe values produced by writes to the
124+
same variable in a different goroutine.
125+
</p>
126+
127+
<h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3>
128+
<p>A summary of the changes between Go releases.</p>
129+
130+
131+
<h2 id="articles">Articles</h2>
132+
133+
{{if not $.GoogleCN}}
134+
<h3 id="blog"><a href="//blog.golang.org/">The Go Blog</a></h3>
135+
<p>The official blog of the Go project, featuring news and in-depth articles by
136+
the Go team and guests.</p>
137+
{{end}}
138+
139+
<h4>Codewalks</h4>
140+
<p>
141+
Guided tours of Go programs.
142+
</p>
143+
<ul>
144+
<li><a href="/doc/codewalk/functions">First-Class Functions in Go</a></li>
145+
<li><a href="/doc/codewalk/markov">Generating arbitrary text: a Markov chain algorithm</a></li>
146+
<li><a href="/doc/codewalk/sharemem">Share Memory by Communicating</a></li>
147+
<li><a href="/doc/articles/wiki/">Writing Web Applications</a> - building a simple web application.</li>
148+
</ul>
149+
150+
{{if not $.GoogleCN}}
151+
<h4>Language</h4>
152+
<ul>
153+
<li><a href="/blog/json-rpc-tale-of-interfaces">JSON-RPC: a tale of interfaces</a></li>
154+
<li><a href="/blog/gos-declaration-syntax">Go's Declaration Syntax</a></li>
155+
<li><a href="/blog/defer-panic-and-recover">Defer, Panic, and Recover</a></li>
156+
<li><a href="/blog/go-concurrency-patterns-timing-out-and">Go Concurrency Patterns: Timing out, moving on</a></li>
157+
<li><a href="/blog/go-slices-usage-and-internals">Go Slices: usage and internals</a></li>
158+
<li><a href="/blog/gif-decoder-exercise-in-go-interfaces">A GIF decoder: an exercise in Go interfaces</a></li>
159+
<li><a href="/blog/error-handling-and-go">Error Handling and Go</a></li>
160+
<li><a href="/blog/organizing-go-code">Organizing Go code</a></li>
161+
</ul>
162+
163+
<h4>Packages</h4>
164+
<ul>
165+
<li><a href="/blog/json-and-go">JSON and Go</a> - using the <a href="/pkg/encoding/json/">json</a> package.</li>
166+
<li><a href="/blog/gobs-of-data">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
167+
<li><a href="/blog/laws-of-reflection">The Laws of Reflection</a> - the fundamentals of the <a href="/pkg/reflect/">reflect</a> package.</li>
168+
<li><a href="/blog/go-image-package">The Go image package</a> - the fundamentals of the <a href="/pkg/image/">image</a> package.</li>
169+
<li><a href="/blog/go-imagedraw-package">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>
170+
</ul>
171+
{{end}}
172+
173+
<h4>Tools</h4>
174+
<ul>
175+
<li><a href="/doc/articles/go_command.html">About the Go command</a> - why we wrote it, what it is, what it's not, and how to use it.</li>
176+
<li><a href="/doc/gdb">Debugging Go Code with GDB</a></li>
177+
<li><a href="/doc/articles/race_detector.html">Data Race Detector</a> - a manual for the data race detector.</li>
178+
<li><a href="/doc/asm">A Quick Guide to Go's Assembler</a> - an introduction to the assembler used by Go.</li>
179+
{{if not $.GoogleCN}}
180+
<li><a href="/blog/c-go-cgo">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
181+
<li><a href="/blog/godoc-documenting-go-code">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
182+
<li><a href="/blog/profiling-go-programs">Profiling Go Programs</a></li>
183+
<li><a href="/blog/race-detector">Introducing the Go Race Detector</a> - an introduction to the race detector.</li>
184+
{{end}}
185+
</ul>
186+
187+
<h4 id="articles_more">More</h4>
188+
<p>
189+
See the <a href="/wiki/Articles">Articles page</a> at the
190+
<a href="/wiki">Wiki</a> for more Go articles.
191+
</p>
192+
193+
{{if not $.GoogleCN}}
194+
<h2 id="talks">Talks</h2>
195+
196+
<img class="gopher" src="/doc/gopher/talks.png"/>
197+
198+
<h3 id="video_tour_of_go"><a href="https://research.swtch.com/gotour">A Video Tour of Go</a></h3>
199+
<p>
200+
Three things that make Go fast, fun, and productive:
201+
interfaces, reflection, and concurrency. Builds a toy web crawler to
202+
demonstrate these.
203+
</p>
204+
205+
<h3 id="go_code_that_grows"><a href="//vimeo.com/53221560">Code that grows with grace</a></h3>
206+
<p>
207+
One of Go's key design goals is code adaptability; that it should be easy to take a simple design and build upon it in a clean and natural way. In this talk Andrew Gerrand describes a simple "chat roulette" server that matches pairs of incoming TCP connections, and then use Go's concurrency mechanisms, interfaces, and standard library to extend it with a web interface and other features. While the function of the program changes dramatically, Go's flexibility preserves the original design as it grows.
208+
</p>
209+
210+
<h3 id="go_concurrency_patterns"><a href="//www.youtube.com/watch?v=f6kdp27TYZs">Go Concurrency Patterns</a></h3>
211+
<p>
212+
Concurrency is the key to designing high performance network services. Go's concurrency primitives (goroutines and channels) provide a simple and efficient means of expressing concurrent execution. In this talk we see how tricky concurrency problems can be solved gracefully with simple Go code.
213+
</p>
214+
215+
<h3 id="advanced_go_concurrency_patterns"><a href="//www.youtube.com/watch?v=QDDwwePbDtw">Advanced Go Concurrency Patterns</a></h3>
216+
<p>
217+
This talk expands on the <i>Go Concurrency Patterns</i> talk to dive deeper into Go's concurrency primitives.
218+
</p>
219+
220+
<h4 id="talks_more">More</h4>
221+
<p>
222+
See the <a href="/talks">Go Talks site</a> and <a href="/wiki/GoTalks">wiki page</a> for more Go talks.
223+
</p>
224+
{{end}}
225+
226+
<h2 id="nonenglish">Non-English Documentation</h2>
227+
228+
<p>
229+
See the <a href="/wiki/NonEnglish">NonEnglish</a> page
230+
at the <a href="/wiki">Wiki</a> for localized
231+
documentation.
232+
</p>

‎content/static/gen.go

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ var files = []string{
3636
"codewalkdir.html",
3737
"dirlist.html",
3838
"doc/copyright.html",
39+
"doc/docs.html",
3940
"doc/root.html",
4041
"error.html",
4142
"example.html",

0 commit comments

Comments
 (0)