Skip to content

Commit 16d1af8

Browse files
agnivadeandybons
agnivade
authored and
andybons
committed
godoc: group package home page list by root
This CL groups the package list into two groups - standard library(GOROOT), and third-party code(GOPATH). It also wraps the list with a collapsible div header used in the package documentation page. This makes the entire page easy to view and manage, and also makes it consistent with the rest of the pages. To implement this, a new function was added to the filesystem interface which returns the root type of the filesystem. In most cases, it is either GOROOT or GOPATH. There are other kinds of filesystems which are not used in the home page, so additional values have been added to satisfy the interface. A side effect of this is that the html template code has become a bit spaghetti-like with if conditions all over. This is because the same template is used to render a package directory as well as the package home page. A better way is to use two separate templates for the different tasks. This cleans out a lot of the if conditions and make for a much cleaner code. This has been taken care in CL 101295. Fixes golang/go#3305 Fixes golang/go#15020 Change-Id: I876357dc76280a7df2ed08d7c6bc53d9a41e69ab Reviewed-on: https://go-review.googlesource.com/95835 Run-TryBot: Andrew Bonventre <[email protected]> TryBot-Result: Gobot Gobot <[email protected]> Reviewed-by: Andrew Bonventre <[email protected]>
1 parent 5dfd893 commit 16d1af8

File tree

13 files changed

+417
-89
lines changed

13 files changed

+417
-89
lines changed

‎godoc/dirtrees.go

Lines changed: 35 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ import (
1616
"runtime"
1717
"sort"
1818
"strings"
19+
20+
"golang.org/x/tools/godoc/vfs"
1921
)
2022

2123
// Conventional name for directories containing test data.
@@ -24,12 +26,13 @@ import (
2426
const testdataDirName = "testdata"
2527

2628
type Directory struct {
27-
Depth int
28-
Path string // directory path; includes Name
29-
Name string // directory name
30-
HasPkg bool // true if the directory contains at least one package
31-
Synopsis string // package documentation, if any
32-
Dirs []*Directory // subdirectories
29+
Depth int
30+
Path string // directory path; includes Name
31+
Name string // directory name
32+
HasPkg bool // true if the directory contains at least one package
33+
Synopsis string // package documentation, if any
34+
FsRootType string // string representation of vfs.RootType
35+
Dirs []*Directory // subdirectories
3336
}
3437

3538
func isGoFile(fi os.FileInfo) bool {
@@ -195,12 +198,13 @@ func (b *treeBuilder) newDirTree(fset *token.FileSet, path, name string, depth i
195198
}
196199

197200
return &Directory{
198-
Depth: depth,
199-
Path: path,
200-
Name: name,
201-
HasPkg: hasPkgFiles && show, // TODO(bradfitz): add proper Hide field?
202-
Synopsis: synopsis,
203-
Dirs: dirs,
201+
Depth: depth,
202+
Path: path,
203+
Name: name,
204+
HasPkg: hasPkgFiles && show, // TODO(bradfitz): add proper Hide field?
205+
Synopsis: synopsis,
206+
FsRootType: string(b.c.fs.RootType(path)),
207+
Dirs: dirs,
204208
}
205209
}
206210

@@ -298,19 +302,31 @@ func (dir *Directory) lookup(path string) *Directory {
298302
// are useful for presenting an entry in an indented fashion.
299303
//
300304
type DirEntry struct {
301-
Depth int // >= 0
302-
Height int // = DirList.MaxHeight - Depth, > 0
303-
Path string // directory path; includes Name, relative to DirList root
304-
Name string // directory name
305-
HasPkg bool // true if the directory contains at least one package
306-
Synopsis string // package documentation, if any
305+
Depth int // >= 0
306+
Height int // = DirList.MaxHeight - Depth, > 0
307+
Path string // directory path; includes Name, relative to DirList root
308+
Name string // directory name
309+
HasPkg bool // true if the directory contains at least one package
310+
Synopsis string // package documentation, if any
311+
FsRootType string // string representation of vfs.RootType
307312
}
308313

309314
type DirList struct {
310315
MaxHeight int // directory tree height, > 0
311316
List []DirEntry
312317
}
313318

319+
// hasThirdParty checks whether a list of directory entries has packages outside
320+
// the standard library or not.
321+
func hasThirdParty(list []DirEntry) bool {
322+
for _, entry := range list {
323+
if entry.FsRootType == string(vfs.RootTypeGoPath) {
324+
return true
325+
}
326+
}
327+
return false
328+
}
329+
314330
// listing creates a (linear) directory listing from a directory tree.
315331
// If skipRoot is set, the root directory itself is excluded from the list.
316332
// If filter is set, only the directory entries whose paths match the filter
@@ -359,6 +375,7 @@ func (root *Directory) listing(skipRoot bool, filter func(string) bool) *DirList
359375
p.Name = d.Name
360376
p.HasPkg = d.HasPkg
361377
p.Synopsis = d.Synopsis
378+
p.FsRootType = d.FsRootType
362379
list = append(list, p)
363380
}
364381

‎godoc/godoc.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,9 @@ func (p *Presentation) initFuncMap() {
106106

107107
// formatting of PageInfoMode query string
108108
"modeQueryString": modeQueryString,
109+
110+
// check whether to display third party section or not
111+
"hasThirdParty": hasThirdParty,
109112
}
110113
if p.URLForSrc != nil {
111114
p.funcMap["srcLink"] = p.URLForSrc

‎godoc/static/package.html

Lines changed: 98 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -249,59 +249,124 @@ <h2 id="pkg-subdirectories">Subdirectories</h2>
249249
<div id="manual-nav">
250250
<dl>
251251
<dt><a href="#stdlib">Standard library</a></dt>
252+
{{if hasThirdParty .List }}
253+
<dt><a href="#thirdparty">Third party</a></dt>
254+
{{end}}
252255
<dt><a href="#other">Other packages</a></dt>
253256
<dd><a href="#subrepo">Sub-repositories</a></dd>
254257
<dd><a href="#community">Community</a></dd>
255258
</dl>
256259
</div>
257-
<h2 id="stdlib">Standard library</h2>
258-
<img alt="" class="gopher" src="/doc/gopher/pkg.png"/>
259-
{{end}}
260-
261260

262-
<div class="pkg-dir">
263-
<table>
264-
<tr>
265-
<th class="pkg-name">Name</th>
266-
<th class="pkg-synopsis">Synopsis</th>
267-
</tr>
261+
<div id="stdlib" class="toggleVisible">
262+
<div class="collapsed">
263+
<h2 class="toggleButton" title="Click to show Standard library section">Standard library ▹</h2>
264+
</div>
265+
<div class="expanded">
266+
<h2 class="toggleButton" title="Click to hide Standard library section">Standard library ▾</h2>
267+
<img alt="" class="gopher" src="/doc/gopher/pkg.png"/>
268+
{{end}}
269+
<div class="pkg-dir">
270+
<table>
271+
<tr>
272+
<th class="pkg-name">Name</th>
273+
<th class="pkg-synopsis">Synopsis</th>
274+
</tr>
268275

269-
{{if not (or (eq $.Dirname "/src") (eq $.Dirname "/src/cmd") $.DirFlat)}}
270-
<tr>
271-
<td colspan="2"><a href="..">..</a></td>
272-
</tr>
273-
{{end}}
276+
{{if not (or (eq $.Dirname "/src") (eq $.Dirname "/src/cmd") $.DirFlat)}}
277+
<tr>
278+
<td colspan="2"><a href="..">..</a></td>
279+
</tr>
280+
{{end}}
274281

275-
{{range .List}}
276-
{{if $.DirFlat}}
277-
{{if .HasPkg}}
282+
{{if eq $.Dirname "/src"}}
283+
{{range .List}}
278284
<tr>
279-
<td class="pkg-name">
280-
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Path}}</a>
281-
</td>
285+
{{if eq .FsRootType "GOROOT"}}
286+
{{if $.DirFlat}}
287+
{{if .HasPkg}}
288+
<td class="pkg-name">
289+
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Path}}</a>
290+
</td>
291+
{{end}}
292+
{{else}}
293+
<td class="pkg-name" style="padding-left: {{multiply .Depth 20}}px;">
294+
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Name}}</a>
295+
</td>
296+
{{end}}
282297
<td class="pkg-synopsis">
283298
{{html .Synopsis}}
284299
</td>
300+
{{end}}
285301
</tr>
286302
{{end}}
287303
{{else}}
288-
<tr>
289-
<td class="pkg-name" style="padding-left: {{multiply .Depth 20}}px;">
290-
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Name}}</a>
291-
</td>
292-
<td class="pkg-synopsis">
293-
{{html .Synopsis}}
294-
</td>
295-
</tr>
304+
{{range .List}}
305+
<tr>
306+
{{if $.DirFlat}}
307+
{{if .HasPkg}}
308+
<td class="pkg-name">
309+
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Path}}</a>
310+
</td>
311+
{{end}}
312+
{{else}}
313+
<td class="pkg-name" style="padding-left: {{multiply .Depth 20}}px;">
314+
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Name}}</a>
315+
</td>
316+
{{end}}
317+
<td class="pkg-synopsis">
318+
{{html .Synopsis}}
319+
</td>
320+
</tr>
321+
{{end}}
296322
{{end}}
297-
{{end}}
298-
</table>
323+
</table>
324+
</div>
325+
{{if eq $.Dirname "/src"}}
326+
</div>
299327
</div>
300328

329+
{{if hasThirdParty .List }}
330+
<div id="thirdparty" class="toggleVisible">
331+
<div class="collapsed">
332+
<h2 class="toggleButton" title="Click to show Third party section">Third party ▹</h2>
333+
</div>
334+
<div class="expanded">
335+
<h2 class="toggleButton" title="Click to hide Third party section">Third party ▾</h2>
336+
<div class="pkg-dir">
337+
<table>
338+
<tr>
339+
<th class="pkg-name">Name</th>
340+
<th class="pkg-synopsis">Synopsis</th>
341+
</tr>
301342

302-
{{if eq $.Dirname "/src"}}
303-
<h2 id="other">Other packages</h2>
343+
{{range .List}}
344+
<tr>
345+
{{if eq .FsRootType "GOPATH"}}
346+
{{if $.DirFlat}}
347+
{{if .HasPkg}}
348+
<td class="pkg-name">
349+
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Path}}</a>
350+
</td>
351+
{{end}}
352+
{{else}}
353+
<td class="pkg-name" style="padding-left: {{multiply .Depth 20}}px;">
354+
<a href="{{html .Path}}/{{modeQueryString $.Mode | html}}">{{html .Name}}</a>
355+
</td>
356+
{{end}}
357+
<td class="pkg-synopsis">
358+
{{html .Synopsis}}
359+
</td>
360+
{{end}}
361+
</tr>
362+
{{end}}
363+
</table>
364+
</div>
365+
</div>
366+
</div>
367+
{{end}}
304368

369+
<h2 id="other">Other packages</h2>
305370
<h3 id="subrepo">Sub-repositories</h3>
306371
<p>
307372
These packages are part of the Go Project but outside the main Go tree.

0 commit comments

Comments
 (0)