[tools] godoc: add table of contents to Overview section
jimmy frasche (Gerrit)
jimmy frasche has uploaded this change for review.
godoc: add table of contents to Overview section
To aid navigation of large packages this creates
a table of contents from the headers in the package
comment to allow the user to quickly jump to the
relevant section.
Updates golang/go#18342
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 33 insertions(+), 7 deletions(-)
diff --git a/godoc/godoc.go b/godoc/godoc.go
index d6c27d0..9f3b6cf 100644
--- a/godoc/godoc.go
+++ b/godoc/godoc.go
@@ -72,11 +72,12 @@
"infoSnippet_html": p.infoSnippet_htmlFunc,
// formatting of AST nodes
- "node": p.nodeFunc,
- "node_html": p.node_htmlFunc,
- "comment_html": comment_htmlFunc,
- "comment_text": comment_textFunc,
- "sanitize": sanitizeFunc,
+ "node": p.nodeFunc,
+ "node_html": p.node_htmlFunc,
+ "comment_html": comment_htmlFunc,
+ "package_comment_html": package_comment_htmlFunc,
+ "comment_text": comment_textFunc,
+ "sanitize": sanitizeFunc,
// support for URL attributes
"pkgLink": pkgLinkFunc,
@@ -347,6 +348,31 @@
return buf.String()
}
+var headerRx = regexp.MustCompile(`<h3 id="([^"]+)">([^<]+)</h3>`)
+
+func package_comment_htmlFunc(comment string) string {
+ var inner, outer bytes.Buffer
+ doc.ToHTML(&inner, comment, nil)
+ // Extract headers. It would be better to do this by iterating go/doc blocks.
+ matches := headerRx.FindAllSubmatch(inner.Bytes(), -1)
+ if len(matches) == 0 {
+ // No headers, so nothing special to do.
+ return inner.String()
+ }
+ outer.WriteString("<dl><dt>Sections</dt>")
+ for _, match := range matches {
+ id, nm := match[1], match[2]
+ outer.WriteString(`<dd><a href="#`)
+ outer.Write(id)
+ outer.WriteString(`">`)
+ outer.Write(nm)
+ outer.WriteString("</a></dd>")
+ }
+ outer.WriteString("</dl>")
+ outer.ReadFrom(&inner)
+ return outer.String()
+}
+
// punchCardWidth is the number of columns of fixed-width
// characters to assume when wrapping text. Very few people
// use terminals or cards smaller than 80 characters, so 80 it is.
diff --git a/godoc/static/package.html b/godoc/static/package.html
index 1d2d1e3..339b17e 100644
--- a/godoc/static/package.html
+++ b/godoc/static/package.html
@@ -42,7 +42,7 @@
</div>
<div class="expanded">
<h2 class="toggleButton" title="Click to hide Overview section">Overview â–¾</h2>
- {{comment_html .Doc}}
+ {{package_comment_html .Doc}}
</div>
</div>
{{example_html $ ""}}
diff --git a/godoc/static/static.go b/godoc/static/static.go
index 7a5618f..9be129d 100644
--- a/godoc/static/static.go
+++ b/godoc/static/static.go
@@ -1695,7 +1695,7 @@
</div>
<div class="expanded">
<h2 class="toggleButton" title="Click to hide Overview section">Overview â–¾</h2>
- {{comment_html .Doc}}
+ {{package_comment_html .Doc}}
</div>
</div>
{{example_html $ ""}}
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
jimmy frasche uploaded patch set #2 to this change.
x/tools/cmd/godoc: add table of contents for Overview section
To aid navigation of large packages this creates
a table of contents from the headers in the package
comment to allow the user to quickly jump to the
relevant section. It also unifies the short nav
to provide a more complete top-level table of contents.
Updates golang/go#18342
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 38 insertions(+), 9 deletions(-)
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
jimmy frasche uploaded patch set #3 to this change.
x/tools/cmd/godoc: add table of contents for Overview section
To aid navigation of large packages this creates
a table of contents from the headers in the package
comment to allow the user to quickly jump to the
relevant section. It also unifies the short nav
to provide a more complete top-level table of contents.
Updates golang/go#25449
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 38 insertions(+), 9 deletions(-)
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
Yury Smolsky (Gerrit)
Can you provide a screenshot with big table of contents?
jimmy frasche (Gerrit)
Patch Set 3:
Can you provide a screenshot with big table of contents?
https://i.imgur.com/9xhNZcC.png
Note that the repeated Overview is because the docs have their own Overview header.
Agniva De Sarker (Gerrit)
Thanks ! Please add the hashtag "wait-release". R=Go1.12.
Also, I think https://golang.org/pkg/html/template/ might provide a better screenshot example. Since it does not have the "Overview" sub-header.
jimmy frasche (Gerrit)
Thanks ! Please add the hashtag "wait-release". R=Go1.12.
Done
Also, I think https://golang.org/pkg/html/template/ might provide a better screenshot example. Since it does not have the "Overview" sub-header.
Provided https://i.imgur.com/68YA2Td.png
That's a good one.
Agniva De Sarker (Gerrit)
Jimmy - Would you like to do a fresh rebase and get this ready for review ?
jimmy frasche (Gerrit)
jimmy frasche uploaded patch set #4 to this change.
x/tools/cmd/godoc: add table of contents for Overview section
To aid navigation of large packages, this creates
a table of contents from the headers in the package
comment allowing the user to quickly jump to the
relevant section. It also unifies the short nav
to provide a more complete top-level table of contents.
Fixes golang/go#25449
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 33 insertions(+), 8 deletions(-)
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
Patch Set 3:
Jimmy - Would you like to do a fresh rebase and get this ready for review ?
Done.
Agniva De Sarker (Gerrit)
Patch Set 4:
Patch Set 3:
Jimmy - Would you like to do a fresh rebase and get this ready for review ?
Done.
Sorry for the radio silence. I've been meaning to take a look at this. Probably this weekend.
In the mean while, adding Andy so that he can take a look whenever he is back.
Agniva De Sarker (Gerrit)
Really sad that we have to regex-ify the html. But I don't see any other solution unless we get a new api from go/doc.
7 comments:
Patch Set #4, Line 7:
x/tools/cmd/godocgodoc:
Patch Set #4, Line 80:
package_comment_tocAppend with "Func" to be consistent with the rest.
Patch Set #4, Line 356:
var headerRx = regexp.MustCompile(`<h3 id="([^"]+)">([^<]+)</h3>`)Quotes aren't compulsory in an attribute value. Also, single-quotes are valid too. Although we know that go/doc won't output unquoted values, it might be good to be robust.
This will only complicate the regex further :(
Patch Set #4, Line 358:
overviewSectionMaybe "overviewHeader" is a better name ?
Patch Set #4, Line 365:
// Extract headers. It would be better to do this by iterating go/doc blocks.For this go/doc needs to have new API to parse the comment and spit out the headers right ? I mean there is nothing we can do unless this comes from go/doc itself.
Patch Set #4, Line 367:
for _, match := range matches {We already know the no. of matches, so maybe better to `make()` the slice beforehand to prevent re-allocations in the range loop.
File godoc/static/package.html:
Patch Set #4, Line 30:
Can we achieve this through css ?
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
jimmy frasche uploaded patch set #5 to this change.
godoc: add table of contents for Overview section
To aid navigation of large packages, this creates
a table of contents from the headers in the package
comment allowing the user to quickly jump to the
relevant section. It also unifies the short nav
to provide a more complete top-level table of contents.
Fixes golang/go#25449
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 34 insertions(+), 8 deletions(-)
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
7 comments:
Patch Set #4, Line 7:
godoc: add tablegodoc:
Done
Patch Set #4, Line 80:
package_comment_tocAppend with "Func" to be consistent with the rest.
Done
Patch Set #4, Line 356:
var headerRx = regexp.MustCompile(`<h3 id="([^"]+)">([^<]+)</h3>`)
Quotes aren't compulsory in an attribute value. Also, single-quotes are valid too. […]
I don't want to attempt to parse html with a regex. It feels really gross even doing this but the fact that it comes from a single, slow changing source under the same umbrella as this code makes it not entirely unacceptable. Just gross. It would be best if go/doc exposed the parse tree so there'd be no need for shenanigans.
Patch Set #4, Line 358:
overviewHeader
Maybe "overviewHeader" is a better name ?
Done
Patch Set #4, Line 365:
// Extract headers. It would be better to do this by iterating go/doc blocks.
For this go/doc needs to have new API to parse the comment and spit out the headers right ? I mean t […]
Correct.
Patch Set #4, Line 367:
sections = make([]overviewHeader, 0, len(matches))We already know the no. […]
Done
File godoc/static/package.html:
Patch Set #4, Line 30:
Can we achieve this through css ?
Yes, and that would be the correct thing to do. I went with what all the other code is doing for consistency.
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
Agniva De Sarker (Gerrit)
Patch set 5:Code-Review +1
Brad Fitzpatrick (Gerrit)
Sorry, you'll need to rebase & re-run go generate for the static stuff.
jimmy frasche (Gerrit)
jimmy frasche uploaded patch set #6 to this change.
godoc: add table of contents for Overview section
To aid navigation of large packages, this creates
a table of contents from the headers in the package
comment allowing the user to quickly jump to the
relevant section. It also unifies the short nav
to provide a more complete top-level table of contents.
Fixes golang/go#25449
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 33 insertions(+), 7 deletions(-)
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
oops, didn't mean to mail that
jimmy frasche (Gerrit)
jimmy frasche uploaded patch set #7 to this change.
godoc: add table of contents for Overview section
To aid navigation of large packages, this creates
a table of contents from the headers in the package
comment allowing the user to quickly jump to the
relevant section. It also unifies the short nav
to provide a more complete top-level table of contents.
Fixes golang/go#25449
Change-Id: I0e348509d3660d3a665505b5ee1e01c44d13d924
---
M godoc/godoc.go
M godoc/static/package.html
M godoc/static/static.go
3 files changed, 33 insertions(+), 7 deletions(-)
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
jimmy frasche (Gerrit)
that one I meant
Andrew Bonventre (Gerrit)
@dmitshur are we going forward with this?
1 comment:
File godoc/static/package.html:
Patch Set #7, Line 107:
pkg-filesuse quotes with attributes
id="pkg-files"
To view, visit change 69030. To unsubscribe, or for help writing mail filters, visit settings.
Ian Lance Taylor (Gerrit)
I'm not sure what the status of this change is. Do we still want this?
Dmitri Shuralyov (Gerrit)
This fell off my list, unfortunately. I'll try to look.
This CL fixes an issue with Proposal-Accepted label.
However, it's worth to consider the original issue in regard to UX work that is being done as part of pkg.go.dev. It's likely we want to keep documentation rendering in sync between golang.org and pkg.go.dev.
Sean Liao (Gerrit)
Sean Liao abandoned this change![]( "Open in Gerrit")
Related details
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |