search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
123.64k stars 17.61k forks source link

x/tools/cmd/godoc: create table of contents from headings in package overview #25449

Open jimmyfrasche opened 6 years ago

jimmyfrasche commented 6 years ago

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 image

Originally discussed in #18342 The majority of the discussion starting at https://github.com/golang/go/issues/18342#issuecomment-334852344

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

I like that.

rsc commented 6 years ago

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

dsnet commented 6 years ago

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 commented 6 years ago

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

jimmyfrasche commented 6 years ago

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

rsc commented 6 years ago

Ping @griesemer to find reviewer.

agnivade commented 6 years ago

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

dsnet commented 6 years ago

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 commented 6 years ago

It is this - https://github.com/golang/go/issues/26637#issuecomment-422356611.

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 (https://github.com/golang/go/issues/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 commented 6 years ago

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 commented 6 years ago

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.