internal/godoc/dochtml: use natural sorting for items

This ensures that simd/archsimd package items are sorted nicely.
For example:

  "Uint8x64" < "Uint32x16" < "Uint64x8"

Fixes golang/go#77160

Change-Id: Ie08696262496e226120ae1b31ca81e02b7f20c65
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/736561
Auto-Submit: Sean Liao <sean@liao.dev>
kokoro-CI: kokoro <noreply+kokoro@google.com>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
Reviewed-by: Ethan Lee <ethanalee@google.com>
Reviewed-by: Sean Liao <sean@liao.dev>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

Author: egonelbre

internal/godoc/dochtml/dochtml.go

@@ -19,6 +19,7 @@ import (
 	"go/doc"
 	"go/printer"
 	"go/token"
+	"slices"
 	"sort"
 	"strings"
 
@@ -30,6 +31,7 @@ import (
 	"golang.org/x/pkgsite/internal/derrors"
 	"golang.org/x/pkgsite/internal/godoc/dochtml/internal/render"
 	"golang.org/x/pkgsite/internal/log"
+	"golang.org/x/pkgsite/internal/natural"
 	"golang.org/x/text/cases"
 	"golang.org/x/text/language"
 )
@@ -151,9 +153,26 @@ func packageToItems(p *doc.Package, exmap map[string][]*example) (consts, vars,
 	for _, t := range p.Types {
 		types = append(types, typeToItem(t, exmap))
 	}
+
+	slices.SortFunc(consts, compareItems)
+	slices.SortFunc(vars, compareItems)
+	slices.SortFunc(funcs, compareItems)
+	slices.SortFunc(types, compareItems)
+
+	for _, typ := range types {
+		slices.SortFunc(typ.Consts, compareItems)
+		slices.SortFunc(typ.Vars, compareItems)
+		slices.SortFunc(typ.Funcs, compareItems)
+		slices.SortFunc(typ.Methods, compareItems)
+	}
+
 	return consts, vars, funcs, types
 }
 
+func compareItems(a, b *item) int {
+	return natural.Compare(a.Name, b.Name)
+}
+
 func valuesToItems(vs []*doc.Value) []*item {
 	var r []*item
 	for _, v := range vs {
@@ -402,7 +421,7 @@ func collectExamples(p *doc.Package) *examples {
 	sort.SliceStable(exs.List, func(i, j int) bool {
 		// TODO: Break ties by sorting by suffix, unless
 		// not needed because of upstream slice order.
-		return exs.List[i].ParentID < exs.List[j].ParentID
+		return natural.Less(exs.List[i].ParentID, exs.List[j].ParentID)
 	})
 	return exs
 }

internal/godoc/dochtml/dochtml_test.go

@@ -48,7 +48,7 @@ var testRenderOptions = RenderOptions{
 func TestRender(t *testing.T) {
 	ctx := context.Background()
 	LoadTemplates(templateFS)
-	for _, pkg := range []string{"everydecl", "comments"} {
+	for _, pkg := range []string{"everydecl", "comments", "order"} {
 		t.Run(pkg, func(t *testing.T) {
 			fset, d := mustLoadPackage(pkg)
 			parts, err := Render(ctx, fset, d, testRenderOptions)

internal/godoc/dochtml/testdata/order.go

@@ -0,0 +1,55 @@
+// Copyright 2026 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package order exercises natural sorting of symbols.
+package order
+
+// Uint32x16 represents a 128-bit unsigned integer.
+type Uint32x16 struct {
+	data [16]uint32
+}
+
+// AsUint8x64 converts a Uint32x16 to a Uint8x64.
+func (u Uint32x16) AsUint8x64() Uint8x64 {
+	return Uint8x64{}
+}
+
+// AsUint64x8 converts a Uint32x16 to a Uint64x8.
+func (u Uint32x16) AsUint64x8() Uint8x64 {
+	return Uint64x8{}
+}
+
+// Uint8x64 represents a 128-bit unsigned integer.
+type Uint8x64 struct {
+	data [64]uint8
+}
+
+// AsUint32x16 converts a Uint8x64 to a Uint32x16.
+func (u Uint8x64) AsUint32x16() Uint32x16 {
+	return Uint32x16{}
+}
+
+// AsUint64x8 converts a Uint8x64 to a Uint64x8.
+func (u Uint8x64) AsUint64x8() Uint64x8 {
+	return Uint64x8{}
+}
+
+// Uint64x8 represents a 128-bit unsigned integer.
+type Uint64x8 struct {
+	data [8]uint64
+}
+
+// AsUint8x64 converts a Uint64x8 to a Uint8x64.
+func (u Uint64x8) AsUint8x64() Uint8x64 {
+	return Uint8x64{}
+}
+
+// AsUint32x16 converts a Uint64x8 to a Uint32x16.
+func (u Uint64x8) AsUint32x16() Uint32x16 {
+	return Uint32x16{}
+}
+
+func ExampleUint64x8_AsUint32x16() {}
+
+func ExampleUint64x8_AsUint8x64() {}