Skip to content

Commit 462deaf

Browse files
jbajba
committed
internal/godoc/dochtml,content/static: preliminary deprecated display
For golang/go#40850 Change-Id: If1631c6d56c694dbeee28e4475b0ddaec316d990 Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/314129 Trust: Jonathan Amsterdam <[email protected]> Run-TryBot: Jonathan Amsterdam <[email protected]> TryBot-Result: kokoro <[email protected]> Reviewed-by: Jamal Carvalho <[email protected]>
1 parent bd1d5f7 commit 462deaf

File tree

7 files changed

+666
-47
lines changed

7 files changed

+666
-47
lines changed

‎content/static/css/stylesheet.css

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1470,6 +1470,28 @@ pre,
14701470
word-wrap: break-word;
14711471
}
14721472

1473+
.Documentation-indexDeprecated {
1474+
font-size: 0.875rem;
1475+
font-style: italic;
1476+
color: var(--gray-3);
1477+
margin-left: 0.5rem;
1478+
}
1479+
1480+
.Documentation-bodyDeprecated {
1481+
font-size: 1rem;
1482+
font-style: italic;
1483+
font-weight: 400;
1484+
color: var(--gray-3);
1485+
margin-left: 0.5rem;
1486+
margin-right: 0.5rem;
1487+
}
1488+
1489+
.Documentation-deprecatedShowLink {
1490+
font-size: 1rem;
1491+
font-weight: 400;
1492+
}
1493+
1494+
14731495
.Unit-content .Versions {
14741496
margin-top: 1rem;
14751497
}

‎content/static/html/doc/body.tmpl

Lines changed: 59 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -22,20 +22,39 @@
2222
{{- range .Funcs -}}
2323
<li class="Documentation-indexFunction">
2424
<a href="#{{.Name}}">{{render_synopsis .Decl}}</a>
25+
{{- if .IsDeprecated -}}
26+
<span class="Documentation-indexDeprecated">deprecated</span>
27+
{{- end -}}
2528
</li>{{"\n"}}
2629
{{- end -}}
2730

2831
{{- range .Types -}}
2932
{{- $tname := .Name -}}
30-
<li class="Documentation-indexType"><a href="#{{$tname}}">type {{$tname}}</a></li>{{"\n"}}
33+
<li class="Documentation-indexType"><a href="#{{$tname}}">type {{$tname}}</a>
34+
{{- if .IsDeprecated -}}
35+
<span class="Documentation-indexDeprecated">deprecated</span>
36+
{{- end -}}
37+
</li>{{"\n"}}
3138
{{- with .Funcs -}}
3239
<li><ul class="Documentation-indexTypeFunctions">{{"\n" -}}
33-
{{range .}}<li><a href="#{{.Name}}">{{render_synopsis .Decl}}</a></li>{{"\n"}}{{end}}
40+
{{range .}}
41+
<li><a href="#{{.Name}}">{{render_synopsis .Decl}}</a>
42+
{{- if .IsDeprecated -}}
43+
<span class="Documentation-indexDeprecated">deprecated</span>
44+
{{- end -}}
45+
</li>{{"\n"}}
46+
{{end}}
3447
</ul></li>{{"\n" -}}
3548
{{- end -}}
3649
{{- with .Methods -}}
3750
<li><ul class="Documentation-indexTypeMethods">{{"\n" -}}
38-
{{range .}}<li><a href="#{{$tname}}.{{.Name}}">{{render_synopsis .Decl}}</a></li>{{"\n"}}{{end}}
51+
{{range .}}
52+
<li><a href="#{{$tname}}.{{.Name}}">{{render_synopsis .Decl}}</a>
53+
{{- if .IsDeprecated -}}
54+
<span class="Documentation-indexDeprecated">deprecated</span>
55+
{{- end -}}
56+
</li>{{"\n"}}
57+
{{end}}
3958
</ul></li>{{"\n" -}}
4059
{{- end -}}
4160
{{- end -}}
@@ -86,11 +105,19 @@
86105
<div class="Documentation-function">
87106
{{- $id := safe_id .Name -}}
88107
<h4 tabindex="-1" id="{{$id}}" data-kind="function" class="Documentation-functionHeader">
89-
<span>func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
108+
<span>
109+
func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a>
110+
{{- if .IsDeprecated -}}
111+
<span class="Documentation-bodyDeprecated">deprecated</span>
112+
<a class="Documentation-deprecatedShowLink" href="?">Show</a>
113+
{{- end -}}
114+
</span>
90115
{{- template "since_version" .Name -}}
91116
</h4>{{"\n"}}
92-
{{- template "declaration" . -}}
93-
{{- template "example" (index $.Examples.Map .Name) -}}
117+
{{if not .IsDeprecated}}
118+
{{- template "declaration" . -}}
119+
{{- template "example" (index $.Examples.Map .Name) -}}
120+
{{end}}
94121
</div>
95122
{{- end -}}
96123
{{- else -}}
@@ -109,8 +136,10 @@
109136
<span>type {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
110137
{{- template "since_version" .Name -}}
111138
</h4>{{"\n"}}
112-
{{- template "declaration" . -}}
113-
{{- template "example" (index $.Examples.Map .Name) -}}
139+
{{if not .IsDeprecated}}
140+
{{- template "declaration" . -}}
141+
{{- template "example" (index $.Examples.Map .Name) -}}
142+
{{end}}
114143

115144
{{- range .Consts -}}
116145
<div class="Documentation-typeConstant">
@@ -128,11 +157,19 @@
128157
<div class="Documentation-typeFunc">
129158
{{- $id := safe_id .Name -}}
130159
<h4 tabindex="-1" id="{{$id}}" data-kind="function" class="Documentation-typeFuncHeader">
131-
<span>func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
160+
<span>
161+
func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a>
162+
{{- if .IsDeprecated -}}
163+
<span class="Documentation-bodyDeprecated">deprecated</span>
164+
<a class="Documentation-deprecatedShowLink" href="?">Show</a>
165+
{{- end -}}
166+
</span>
132167
{{- template "since_version" .Name -}}
133168
</h4>{{"\n"}}
134-
{{- template "declaration" . -}}
135-
{{- template "example" (index $.Examples.Map .Name) -}}
169+
{{if not .IsDeprecated}}
170+
{{- template "declaration" . -}}
171+
{{- template "example" (index $.Examples.Map .Name) -}}
172+
{{end}}
136173
</div>
137174
{{- end -}}
138175

@@ -141,11 +178,19 @@
141178
{{- $name := (printf "%s.%s" $tname .Name) -}}
142179
{{- $id := (safe_id $name) -}}
143180
<h4 tabindex="-1" id="{{$id}}" data-kind="method" class="Documentation-typeMethodHeader">
144-
<span>func ({{.Recv}}) {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
181+
<span>
182+
func ({{.Recv}}) {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a>
183+
{{- if .IsDeprecated -}}
184+
<span class="Documentation-bodyDeprecated">deprecated</span>
185+
<a class="Documentation-deprecatedShowLink" href="?">Show</a>
186+
{{- end -}}
187+
</span>
145188
{{- template "since_version" $name -}}
146189
</h4>{{"\n"}}
147-
{{- template "declaration" . -}}
148-
{{- template "example" (index $.Examples.Map $name) -}}
190+
{{if not .IsDeprecated}}
191+
{{- template "declaration" . -}}
192+
{{- template "example" (index $.Examples.Map $name) -}}
193+
{{end}}
149194
</div>
150195
{{- end -}}
151196
</div>

‎internal/godoc/dochtml/dochtml.go

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,9 @@ import (
2525
"github.com/google/safehtml/legacyconversions"
2626
"github.com/google/safehtml/template"
2727
"github.com/google/safehtml/uncheckedconversions"
28+
"golang.org/x/pkgsite/internal"
2829
"golang.org/x/pkgsite/internal/derrors"
30+
"golang.org/x/pkgsite/internal/experiment"
2931
"golang.org/x/pkgsite/internal/godoc/dochtml/internal/render"
3032
"golang.org/x/pkgsite/internal/godoc/internal/doc"
3133
)
@@ -91,6 +93,28 @@ func Render(ctx context.Context, fset *token.FileSet, p *doc.Package, opt Render
9193
opt.Limit = 10 * megabyte
9294
}
9395

96+
if !experiment.IsActive(ctx, internal.ExperimentDeprecatedDoc) {
97+
//Simpler to clear the fields here than to add experiment checks in the templates.
98+
for _, c := range p.Consts {
99+
c.IsDeprecated = false
100+
}
101+
for _, v := range p.Vars {
102+
v.IsDeprecated = false
103+
}
104+
for _, f := range p.Funcs {
105+
f.IsDeprecated = false
106+
}
107+
for _, t := range p.Types {
108+
t.IsDeprecated = false
109+
for _, f := range t.Funcs {
110+
f.IsDeprecated = false
111+
}
112+
for _, m := range t.Methods {
113+
m.IsDeprecated = false
114+
}
115+
}
116+
}
117+
94118
funcs, data, links := renderInfo(ctx, fset, p, opt)
95119
p = data.Package
96120
if docIsEmpty(p) {

‎internal/godoc/dochtml/dochtml_test.go

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ var testRenderOptions = RenderOptions{
3939
SinceVersionFunc: func(string) string { return "" },
4040
}
4141

42-
func TestRenderParts(t *testing.T) {
42+
func TestRender(t *testing.T) {
4343
ctx := context.Background()
4444
LoadTemplates(templateSource)
4545

@@ -50,15 +50,6 @@ func TestRenderParts(t *testing.T) {
5050
}
5151
compareWithGolden(t, parts, "everydecl", *update)
5252

53-
if experiment.IsActive(ctx, internal.ExperimentDeprecatedDoc) {
54-
fset2, d2 := mustLoadPackage("deprecated")
55-
parts2, err := Render(ctx, fset2, d2, testRenderOptions)
56-
if err != nil {
57-
t.Fatal(err)
58-
}
59-
compareWithGolden(t, parts2, "deprecated", *update)
60-
}
61-
6253
bodyDoc, err := html.Parse(strings.NewReader(parts.Body.String()))
6354
if err != nil {
6455
t.Fatal(err)
@@ -82,6 +73,21 @@ func TestRenderParts(t *testing.T) {
8273
}
8374
}
8475

76+
func TestRenderDeprecated(t *testing.T) {
77+
compare := func(ctx context.Context, name string) {
78+
t.Helper()
79+
fset, d := mustLoadPackage("deprecated")
80+
parts, err := Render(ctx, fset, d, testRenderOptions)
81+
if err != nil {
82+
t.Fatal(err)
83+
}
84+
compareWithGolden(t, parts, name, *update)
85+
}
86+
87+
compare(context.Background(), "deprecated-off")
88+
compare(experiment.NewContext(context.Background(), internal.ExperimentDeprecatedDoc), "deprecated-on")
89+
}
90+
8591
func compareWithGolden(t *testing.T, parts *Parts, name string, update bool) {
8692
got := fmt.Sprintf("%s\n----\n%s\n----\n%s\n", parts.Body, parts.Outline, parts.MobileOutline)
8793
testhelper.CompareWithGolden(t, got, name+".golden", update)

0 commit comments

Comments
 (0)