diff --git a/content/static/css/stylesheet.css b/content/static/css/stylesheet.css index 8c9fb8062..5aa894df8 100644 --- a/content/static/css/stylesheet.css +++ b/content/static/css/stylesheet.css @@ -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; } diff --git a/content/static/html/doc/body.tmpl b/content/static/html/doc/body.tmpl index 6574664eb..ff3a0dec4 100644 --- a/content/static/html/doc/body.tmpl +++ b/content/static/html/doc/body.tmpl @@ -22,20 +22,39 @@ {{- range .Funcs -}}
  • {{render_synopsis .Decl}} + {{- if .IsDeprecated -}} + deprecated + {{- end -}}
    • {{"\n"}} {{- end -}} {{- range .Types -}} {{- $tname := .Name -}} -
  • type {{$tname}}
    • {{"\n"}} +
  • type {{$tname}} + {{- if .IsDeprecated -}} + deprecated + {{- end -}} +
    • {{"\n"}} {{- with .Funcs -}}
    • {{"\n" -}} {{- end -}} {{- with .Methods -}}
    • {{"\n" -}} {{- end -}} {{- end -}} @@ -86,11 +105,19 @@
    {{- $id := safe_id .Name -}}

    - func {{source_link .Name .Decl}} + + func {{source_link .Name .Decl}} + {{- if .IsDeprecated -}} + deprecated + Show + {{- end -}} + {{- template "since_version" .Name -}}

    {{"\n"}} - {{- template "declaration" . -}} - {{- template "example" (index $.Examples.Map .Name) -}} + {{if not .IsDeprecated}} + {{- template "declaration" . -}} + {{- template "example" (index $.Examples.Map .Name) -}} + {{end}}
    {{- end -}} {{- else -}} @@ -109,8 +136,10 @@ type {{source_link .Name .Decl}} {{- template "since_version" .Name -}} {{"\n"}} - {{- template "declaration" . -}} - {{- template "example" (index $.Examples.Map .Name) -}} + {{if not .IsDeprecated}} + {{- template "declaration" . -}} + {{- template "example" (index $.Examples.Map .Name) -}} + {{end}} {{- range .Consts -}}
    @@ -128,11 +157,19 @@
    {{- $id := safe_id .Name -}}

    - func {{source_link .Name .Decl}} + + func {{source_link .Name .Decl}} + {{- if .IsDeprecated -}} + deprecated + Show + {{- end -}} + {{- template "since_version" .Name -}}

    {{"\n"}} - {{- template "declaration" . -}} - {{- template "example" (index $.Examples.Map .Name) -}} + {{if not .IsDeprecated}} + {{- template "declaration" . -}} + {{- template "example" (index $.Examples.Map .Name) -}} + {{end}}
    {{- end -}} @@ -141,11 +178,19 @@ {{- $name := (printf "%s.%s" $tname .Name) -}} {{- $id := (safe_id $name) -}}

    - func ({{.Recv}}) {{source_link .Name .Decl}} + + func ({{.Recv}}) {{source_link .Name .Decl}} + {{- if .IsDeprecated -}} + deprecated + Show + {{- end -}} + {{- template "since_version" $name -}}

    {{"\n"}} - {{- template "declaration" . -}} - {{- template "example" (index $.Examples.Map $name) -}} + {{if not .IsDeprecated}} + {{- template "declaration" . -}} + {{- template "example" (index $.Examples.Map $name) -}} + {{end}}
    {{- end -}} diff --git a/internal/godoc/dochtml/dochtml.go b/internal/godoc/dochtml/dochtml.go index 6da7bbe64..ba2538d4d 100644 --- a/internal/godoc/dochtml/dochtml.go +++ b/internal/godoc/dochtml/dochtml.go @@ -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" ) @@ -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) { diff --git a/internal/godoc/dochtml/dochtml_test.go b/internal/godoc/dochtml/dochtml_test.go index af2cb6382..a78027c09 100644 --- a/internal/godoc/dochtml/dochtml_test.go +++ b/internal/godoc/dochtml/dochtml_test.go @@ -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) @@ -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) @@ -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) diff --git a/internal/godoc/dochtml/testdata/deprecated-off.golden b/internal/godoc/dochtml/testdata/deprecated-off.golden new file mode 100644 index 000000000..cbc7370c1 --- /dev/null +++ b/internal/godoc/dochtml/testdata/deprecated-off.golden @@ -0,0 +1,382 @@ + +
    +

    Overview

    + +
    +
      +

      Package deprecated has some deprecated symbols. +

      +
      +

      Index

      + + +

      Constants

      + +
      +
      + View Source + 
      const BadC = 2
      +
      +
      +
        +

        BadC is bad. +Deprecated: use GoodC. +

        + +
        + View Source + 
        const GoodC = 1
        +
        + +
        + +

        Variables

        + +
        +
        + View Source + 
        var BadV = 2
        +
        +
        +
          +

          Deprecated: use GoodV. +

          + +
          + View Source + 
          var GoodV = 1
          +
          + +
          + +

          Functions

          + +

          + + func BadF + + + +

          + + +
          + 
          func BadF()
          +
          +
          +
            +

            BadF is bad. +Deprecated: use GoodF. +

            + +

            + + func GoodF + + + +

            + + +
            + 
            func GoodF()
            +
            + + +
            + +

            Types

            + +

            + type BadT + + + +

            + + +
            + 
            type BadT int
            +
            +
            +
              +

              BadT is bad. +Deprecated: use GoodT. +Don't use this. +

              +

              + type GoodT + + + +

              + + +
              + 
              type GoodT int
              +
              + +

              + + func NewGoodTBad + + + +

              + + +
              + 
              func NewGoodTBad() GoodT
              +
              +
              +
                +

                NewGoodTBad is bad. +Deprecated: use NewGoodTGood. +

                + +

                + + func NewGoodTGood + + + +

                + + +
                + 
                func NewGoodTGood() GoodT
                +
                + + +

                + + func (GoodT) BadM + + + +

                + + +
                + 
                func (GoodT) BadM()
                +
                +
                +
                  +

                  BadM is bad. +Deprecated: use GoodM. +

                  + +

                  + + func (GoodT) GoodM + + + +

                  + + +
                  + 
                  func (GoodT) GoodM()
                  +
                  + + +
                  + +---- + + + +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/internal/godoc/dochtml/testdata/deprecated.golden b/internal/godoc/dochtml/testdata/deprecated-on.golden similarity index 54% rename from internal/godoc/dochtml/testdata/deprecated.golden rename to internal/godoc/dochtml/testdata/deprecated-on.golden index dc20332fc..eef9c320c 100644 --- a/internal/godoc/dochtml/testdata/deprecated.golden +++ b/internal/godoc/dochtml/testdata/deprecated-on.golden @@ -13,21 +13,43 @@
                • Constants
                • Variables
                • - func GoodF() -
                  • + func BadF()deprecated +
                • + func GoodF()
                  • +
                • type BadTdeprecated
                • type GoodT

                  • Constants

                  +
                  + View Source + 
                  const BadC = 2
                  +
                  +
                  + +

                  BadC is bad. +Deprecated: use GoodC. +

                  +
                  View Source 
                  const GoodC = 1
                  @@ -38,6 +60,15 @@

                  Variables

                  +
                  + View Source + 
                  var BadV = 2
                  +
                  +
                  +
                    +

                    Deprecated: use GoodV. +

                    +
                    View Source 
                    var GoodV = 1
                    @@ -47,55 +78,103 @@

                    Functions

                    -

                    - func GoodF +

                    + + func BadF deprecated + Show

                    + +

                    + + func GoodF + + + +

                    + + 
                    func GoodF()
                    -
                    + +

                    Types

                    -

                    +

                    + type BadT + + + +

                    + +

                    type GoodT

                    + 
                    type GoodT int
                    -

                    - func NewGoodTGood +

                    + + func NewGoodTBad deprecated + Show + + + +

                    + + +

                    + + func NewGoodTGood

                    + 
                    func NewGoodTGood() GoodT
                    -

                    - func (GoodT) GoodM + +

                    + + func (GoodT) BadM deprecated + Show

                    + +

                    + + func (GoodT) GoodM + + + +

                    + + 
                    func (GoodT) GoodM()
                    -

                    + +
                    + ----