Skip to content

Commit

Permalink
internal/godoc/dochtml,content/static: preliminary deprecated display
Browse files Browse the repository at this point in the history 
For golang/go#40850

Change-Id: If1631c6d56c694dbeee28e4475b0ddaec316d990
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/314129
Trust: Jonathan Amsterdam <jba@google.com>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: kokoro <noreply+kokoro@google.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
  • Loading branch information
@jba
jba committed Apr 27, 2021
1 parent bd1d5f7 commit 462deaf
Show file tree
Hide file tree
Showing 7 changed files with 666 additions and 47 deletions.
22 changes: 22 additions & 0 deletions content/static/css/stylesheet.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1470,6 +1470,28 @@ pre,
word-wrap: break-word;
}

.Documentation-indexDeprecated {
font-size: 0.875rem;
font-style: italic;
color: var(--gray-3);
margin-left: 0.5rem;
}

.Documentation-bodyDeprecated {
font-size: 1rem;
font-style: italic;
font-weight: 400;
color: var(--gray-3);
margin-left: 0.5rem;
margin-right: 0.5rem;
}

.Documentation-deprecatedShowLink {
font-size: 1rem;
font-weight: 400;
}


.Unit-content .Versions {
margin-top: 1rem;
}
Expand Down
73 changes: 59 additions & 14 deletions content/static/html/doc/body.tmpl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,39 @@
{{- range .Funcs -}}
<li class="Documentation-indexFunction">
<a href="#{{.Name}}">{{render_synopsis .Decl}}</a>
{{- if .IsDeprecated -}}
<span class="Documentation-indexDeprecated">deprecated</span>
{{- end -}}
</li>{{"\n"}}
{{- end -}}

{{- range .Types -}}
{{- $tname := .Name -}}
<li class="Documentation-indexType"><a href="#{{$tname}}">type {{$tname}}</a></li>{{"\n"}}
<li class="Documentation-indexType"><a href="#{{$tname}}">type {{$tname}}</a>
{{- if .IsDeprecated -}}
<span class="Documentation-indexDeprecated">deprecated</span>
{{- end -}}
</li>{{"\n"}}
{{- with .Funcs -}}
<li><ul class="Documentation-indexTypeFunctions">{{"\n" -}}
{{range .}}<li><a href="#{{.Name}}">{{render_synopsis .Decl}}</a></li>{{"\n"}}{{end}}
{{range .}}
<li><a href="#{{.Name}}">{{render_synopsis .Decl}}</a>
{{- if .IsDeprecated -}}
<span class="Documentation-indexDeprecated">deprecated</span>
{{- end -}}
</li>{{"\n"}}
{{end}}
</ul></li>{{"\n" -}}
{{- end -}}
{{- with .Methods -}}
<li><ul class="Documentation-indexTypeMethods">{{"\n" -}}
{{range .}}<li><a href="#{{$tname}}.{{.Name}}">{{render_synopsis .Decl}}</a></li>{{"\n"}}{{end}}
{{range .}}
<li><a href="#{{$tname}}.{{.Name}}">{{render_synopsis .Decl}}</a>
{{- if .IsDeprecated -}}
<span class="Documentation-indexDeprecated">deprecated</span>
{{- end -}}
</li>{{"\n"}}
{{end}}
</ul></li>{{"\n" -}}
{{- end -}}
{{- end -}}
Expand Down Expand Up @@ -86,11 +105,19 @@
<div class="Documentation-function">
{{- $id := safe_id .Name -}}
<h4 tabindex="-1" id="{{$id}}" data-kind="function" class="Documentation-functionHeader">
<span>func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
<span>
func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a>
{{- if .IsDeprecated -}}
<span class="Documentation-bodyDeprecated">deprecated</span>
<a class="Documentation-deprecatedShowLink" href="?">Show</a>
{{- end -}}
</span>
{{- template "since_version" .Name -}}
</h4>{{"\n"}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map .Name) -}}
{{if not .IsDeprecated}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map .Name) -}}
{{end}}
</div>
{{- end -}}
{{- else -}}
Expand All @@ -109,8 +136,10 @@
<span>type {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
{{- template "since_version" .Name -}}
</h4>{{"\n"}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map .Name) -}}
{{if not .IsDeprecated}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map .Name) -}}
{{end}}

{{- range .Consts -}}
<div class="Documentation-typeConstant">
Expand All @@ -128,11 +157,19 @@
<div class="Documentation-typeFunc">
{{- $id := safe_id .Name -}}
<h4 tabindex="-1" id="{{$id}}" data-kind="function" class="Documentation-typeFuncHeader">
<span>func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
<span>
func {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a>
{{- if .IsDeprecated -}}
<span class="Documentation-bodyDeprecated">deprecated</span>
<a class="Documentation-deprecatedShowLink" href="?">Show</a>
{{- end -}}
</span>
{{- template "since_version" .Name -}}
</h4>{{"\n"}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map .Name) -}}
{{if not .IsDeprecated}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map .Name) -}}
{{end}}
</div>
{{- end -}}

Expand All @@ -141,11 +178,19 @@
{{- $name := (printf "%s.%s" $tname .Name) -}}
{{- $id := (safe_id $name) -}}
<h4 tabindex="-1" id="{{$id}}" data-kind="method" class="Documentation-typeMethodHeader">
<span>func ({{.Recv}}) {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a></span>
<span>
func ({{.Recv}}) {{source_link .Name .Decl}} <a class="Documentation-idLink" href="#{{$id}}">¶</a>
{{- if .IsDeprecated -}}
<span class="Documentation-bodyDeprecated">deprecated</span>
<a class="Documentation-deprecatedShowLink" href="?">Show</a>
{{- end -}}
</span>
{{- template "since_version" $name -}}
</h4>{{"\n"}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map $name) -}}
{{if not .IsDeprecated}}
{{- template "declaration" . -}}
{{- template "example" (index $.Examples.Map $name) -}}
{{end}}
</div>
{{- end -}}
</div>
Expand Down
24 changes: 24 additions & 0 deletions internal/godoc/dochtml/dochtml.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,9 @@ import (
"github.com/google/safehtml/legacyconversions"
"github.com/google/safehtml/template"
"github.com/google/safehtml/uncheckedconversions"
"golang.org/x/pkgsite/internal"
"golang.org/x/pkgsite/internal/derrors"
"golang.org/x/pkgsite/internal/experiment"
"golang.org/x/pkgsite/internal/godoc/dochtml/internal/render"
"golang.org/x/pkgsite/internal/godoc/internal/doc"
)
Expand Down Expand Up @@ -91,6 +93,28 @@ func Render(ctx context.Context, fset *token.FileSet, p *doc.Package, opt Render
opt.Limit = 10 * megabyte
}

if !experiment.IsActive(ctx, internal.ExperimentDeprecatedDoc) {
//Simpler to clear the fields here than to add experiment checks in the templates.
for _, c := range p.Consts {
c.IsDeprecated = false
}
for _, v := range p.Vars {
v.IsDeprecated = false
}
for _, f := range p.Funcs {
f.IsDeprecated = false
}
for _, t := range p.Types {
t.IsDeprecated = false
for _, f := range t.Funcs {
f.IsDeprecated = false
}
for _, m := range t.Methods {
m.IsDeprecated = false
}
}
}

funcs, data, links := renderInfo(ctx, fset, p, opt)
p = data.Package
if docIsEmpty(p) {
Expand Down
26 changes: 16 additions & 10 deletions internal/godoc/dochtml/dochtml_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ var testRenderOptions = RenderOptions{
SinceVersionFunc: func(string) string { return "" },
}

func TestRenderParts(t *testing.T) {
func TestRender(t *testing.T) {
ctx := context.Background()
LoadTemplates(templateSource)

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

if experiment.IsActive(ctx, internal.ExperimentDeprecatedDoc) {
fset2, d2 := mustLoadPackage("deprecated")
parts2, err := Render(ctx, fset2, d2, testRenderOptions)
if err != nil {
t.Fatal(err)
}
compareWithGolden(t, parts2, "deprecated", *update)
}

bodyDoc, err := html.Parse(strings.NewReader(parts.Body.String()))
if err != nil {
t.Fatal(err)
Expand All @@ -82,6 +73,21 @@ func TestRenderParts(t *testing.T) {
}
}

func TestRenderDeprecated(t *testing.T) {
compare := func(ctx context.Context, name string) {
t.Helper()
fset, d := mustLoadPackage("deprecated")
parts, err := Render(ctx, fset, d, testRenderOptions)
if err != nil {
t.Fatal(err)
}
compareWithGolden(t, parts, name, *update)
}

compare(context.Background(), "deprecated-off")
compare(experiment.NewContext(context.Background(), internal.ExperimentDeprecatedDoc), "deprecated-on")
}

func compareWithGolden(t *testing.T, parts *Parts, name string, update bool) {
got := fmt.Sprintf("%s\n----\n%s\n----\n%s\n", parts.Body, parts.Outline, parts.MobileOutline)
testhelper.CompareWithGolden(t, got, name+".golden", update)
Expand Down
Loading

0 comments on commit 462deaf

Please sign in to comment.