Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix(internal/godocfx): use correct anchor links #3738

Merged
merged 2 commits into from Feb 25, 2021
Merged

fix(internal/godocfx): use correct anchor links #3738

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3aff05b
fix(internal/godocfx): use correct anchor links
tbpg Feb 25, 2021
26e3800
Merge branch 'master' into godocfx
tbpg Feb 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
100 changes: 85 additions & 15 deletions internal/godocfx/parse.go
View file
Open in desktop
Expand Up @@ -34,6 +34,7 @@ import (
"log"
"os"
"path/filepath"
"regexp"
"sort"
"strconv"
"strings"
Expand Down Expand Up @@ -155,7 +156,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
// Once the files are grouped by package, process each package
// independently.
for _, pi := range pkgInfos {
link := newLinker(pi.pkg.Imports, pi.importRenames)
link := newLinker(pi)
topLevelDecls := pkgsite.TopLevelDecls(pi.doc)
pkgItem := &item{
UID: pi.doc.ImportPath,
Expand Down Expand Up @@ -183,7 +184,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
Type: "const",
Summary: c.Doc,
Langs: onlyGo,
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl, toURL, topLevelDecls)},
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl, link.toURL, topLevelDecls)},
})
}
for _, v := range pi.doc.Vars {
Expand All @@ -199,7 +200,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
Type: "variable",
Summary: v.Doc,
Langs: onlyGo,
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl, toURL, topLevelDecls)},
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl, link.toURL, topLevelDecls)},
})
}
for _, t := range pi.doc.Types {
Expand All @@ -213,7 +214,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
Type: "type",
Summary: t.Doc,
Langs: onlyGo,
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, t.Decl, toURL, topLevelDecls)},
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, t.Decl, link.toURL, topLevelDecls)},
Examples: processExamples(t.Examples, pi.fset),
}
// Note: items are added as page.Children, rather than
Expand All @@ -232,7 +233,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
Type: "const",
Summary: c.Doc,
Langs: onlyGo,
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl, toURL, topLevelDecls)},
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl, link.toURL, topLevelDecls)},
})
}
for _, v := range t.Vars {
Expand All @@ -248,7 +249,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result
Type: "variable",
Summary: v.Doc,
Langs: onlyGo,
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl, toURL, topLevelDecls)},
Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl, link.toURL, topLevelDecls)},
})
}

Expand Down Expand Up @@ -313,18 +314,84 @@ type linker struct {
// Behavior is undefined when a single import has different names in
// different files.
imports map[string]string

// idToAnchor is a map from an ID to the anchor URL for that ID.
idToAnchor map[string]string
}

func newLinker(rawImports map[string]*packages.Package, importSyntax map[string]string) *linker {
func newLinker(pi pkgInfo) *linker {
imports := map[string]string{}
for path, pkg := range rawImports {
for path, pkg := range pi.pkg.Imports {
name := pkg.Name
if rename := importSyntax[path]; rename != "" {
if rename := pi.importRenames[path]; rename != "" {
name = rename
}
imports[name] = path
}
return &linker{imports: imports}

idToAnchor := buildIDToAnchor(pi)

return &linker{imports: imports, idToAnchor: idToAnchor}
}

// nonWordRegex is based on
// https://github.com/googleapis/doc-templates/blob/70eba5908e7b9aef5525d0f1f24194ae750f267e/third_party/docfx/templates/devsite/common.js#L27-L30.
var nonWordRegex = regexp.MustCompile("\\W")

func buildIDToAnchor(pi pkgInfo) map[string]string {
idToAnchor := map[string]string{}
idToAnchor[pi.doc.ImportPath] = pi.doc.ImportPath

for _, c := range pi.doc.Consts {
commaID := strings.Join(c.Names, ",")
uid := pi.doc.ImportPath + "." + commaID
for _, name := range c.Names {
idToAnchor[name] = uid
}
}
for _, v := range pi.doc.Vars {
commaID := strings.Join(v.Names, ",")
uid := pi.doc.ImportPath + "." + commaID
for _, name := range v.Names {
idToAnchor[name] = uid
}
}
for _, f := range pi.doc.Funcs {
uid := pi.doc.ImportPath + "." + f.Name
idToAnchor[f.Name] = uid
}
for _, t := range pi.doc.Types {
uid := pi.doc.ImportPath + "." + t.Name
idToAnchor[t.Name] = uid
for _, c := range t.Consts {
commaID := strings.Join(c.Names, ",")
uid := pi.doc.ImportPath + "." + commaID
for _, name := range c.Names {
idToAnchor[name] = uid
}
}
for _, v := range t.Vars {
commaID := strings.Join(v.Names, ",")
uid := pi.doc.ImportPath + "." + commaID
for _, name := range v.Names {
idToAnchor[name] = uid
}
}
for _, f := range t.Funcs {
uid := pi.doc.ImportPath + "." + t.Name + "." + f.Name
idToAnchor[f.Name] = uid
}
for _, m := range t.Methods {
uid := pi.doc.ImportPath + "." + t.Name + "." + m.Name
idToAnchor[m.Name] = uid
}
}

for id, anchor := range idToAnchor {
idToAnchor[id] = nonWordRegex.ReplaceAllString(anchor, "_")
}

return idToAnchor
}

func (l *linker) linkify(s string) string {
Expand All @@ -342,11 +409,11 @@ func (l *linker) linkify(s string) string {
// If s is not exported, it's probably a builtin.
if !token.IsExported(s) {
if doc.IsPredeclared(s) {
return href(toURL("builtin", s), s)
return href(l.toURL("builtin", s), s)
}
return fmt.Sprintf("%s%s", prefix, s)
}
return fmt.Sprintf("%s%s", prefix, href(toURL("", s), s))
return fmt.Sprintf("%s%s", prefix, href(l.toURL("", s), s))
}
// Otherwise, it's in another package.
split := strings.Split(s, ".")
Expand All @@ -362,14 +429,17 @@ func (l *linker) linkify(s string) string {
return fmt.Sprintf("%s%s", prefix, s)
}
name := split[1]
return fmt.Sprintf("%s%s.%s", prefix, href(toURL(pkgPath, ""), pkg), href(toURL(pkgPath, name), name))
return fmt.Sprintf("%s%s.%s", prefix, href(l.toURL(pkgPath, ""), pkg), href(l.toURL(pkgPath, name), name))
}

// TODO: link to the right baseURL, with the right module name and version
// pattern.
func toURL(pkg, name string) string {
func (l *linker) toURL(pkg, name string) string {
if pkg == "" {
return fmt.Sprintf("#%s", strings.ToLower(name))
if anchor := l.idToAnchor[name]; anchor != "" {
name = anchor
}
return fmt.Sprintf("#%s", name)
}
baseURL := "https://pkg.go.dev"
if name == "" {
Expand Down