x/pkgsite/cmd/pkgsite: create table of contents from headings in package overview

[jimmyfrasche]

Packages with large overviews often have multiple headings.

Creating a table of contents from those headings allows the initial reader to gauge the scope of the package at a glance and allows the return reader to skip easily to the desired section.

Screenshot

Originally discussed in #18342 The majority of the discussion starting at #18342 (comment)

Prototype CL https://golang.org/cl/69030

Per golang.org/s/owners, cc: @andybons @agnivade @bradfitz @griesemer @ysmolsky

cc @dsnet for any interference this may cause with #25444

[agnivade]

I am neutral to this. But if we are to do this, I agree with @neild's comment that this should be merged with the top level table of contents. Having a separate table of contents inside the Overview section feels a bit inconsistent.

[jimmyfrasche]

I don't feel strongly either way on that point: I just did the easiest thing that worked.

But if we're talking consistency the package index is a separate table of contents as is the list of examples (though that's sorta part of the package index?). The ToC at the top is like a super-ToC to the more specific ToCs so adding it to the super-ToC seems less consistent to me.

[agnivade]

Fair enough. Although the links from inside "Index" can be considered as ToC to the rest of the page, whereas if you add the new ToC inside "Overview", it just jumps to headings inside that section.

What do you think about this ?

Overview
    Sub-heading1
    Sub-heading2
Index
    Examples
    Package files

The top level links "Overview" and "Examples", both link to collapsibles. And links under them go inside that collapsible. This also fixes the inconsistency that "Examples" is linkable, but "Package files" is not.

[jimmyfrasche]

I like that.

[rsc]

The suggestion two comments up (one big ToC, not scattered ToC pieces) looks great. @jimmyfrasche, can you update your CL to do that?

[dsnet]

If we're going with the ToC approach, can we please consider how that would work if we ever do #18342?

Edit: I'm not opposed to this, just wanted to sure we think about it.

[gopherbot]

Change https://golang.org/cl/69030 mentions this issue: x/tools/cmd/godoc: add table of contents for Overview section

[jimmyfrasche]

@rsc I've updated the CL. Not sure who to add for reviewers but all are welcome.

[rsc]

Ping @griesemer to find reviewer.

[agnivade]

@spf13 - Is this part of the new redesign too ? Or we can get this in ?

[dsnet]

Is there a re-design that I don't know about? I've been trying to make the case that there needs to be a cohesive plan for how godoc is going to evolve before adding lots of ad-hoc features.

[agnivade]

It is this - #26637 (comment).

I was also surprised because there has been no proposal document for the re-design, nor there are any reviews floating around.

Totally agree that there needs to be a cohesive plan for godoc. For 1.12, I thought the sidebar(#26637), toc (this issue), and build tags (#3398) are good things to get in. But now there is this re-design about which there seems to be no visibility.

@spf13 - Can we get some clarity on what exactly the re-design will do ? Ideally it would be great if there is a proposal issue for all to see. Otherwise, it is very disheartening to spend effort on analyzing proposals and reviewing CLs only to find that all of it is redundant.

[spf13]

As part of the new branding we are planning to revamp our entire web presence. We are first starting with the blog which should launch in the next week or so.

This is laying the foundation for all of the remaining web redesign work. After the blog we will be focused on the static pages on the website.

We have mockups for a large amount of the pages and designs for reusable components to cover much of what we are looking to do. Additionally @dmitshur has joined the team and is dedicating time to updating our web stuff.

I'm very hesitant to share the mocks as to avoid bikeshedding them... especially as they are guides, not pixel perfect specs.

[agnivade]

I'm very hesitant to share the mocks as to avoid bikeshedding them... especially as they are guides, not pixel perfect specs.

Ok, it is your call anyways. Would you be able to clarify whether a toc such as this issue is also going to be done or not ? I would like to avoid doing redundant work if possible.

[seankhliao]

I believe this was done for pkgsite.