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.

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

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

Open
jimmyfrasche opened this Issue May 17, 2018 · 14 comments

Comments

Projects
None yet
6 participants
@jimmyfrasche
Member

jimmyfrasche commented May 17, 2018

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 #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

@gopherbot gopherbot added this to the Proposal milestone May 17, 2018

@gopherbot gopherbot added the Proposal label May 17, 2018

@agnivade

This comment has been minimized.

Member

agnivade commented May 18, 2018

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

This comment has been minimized.

Member

jimmyfrasche commented May 18, 2018

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

This comment has been minimized.

Member

agnivade commented May 18, 2018

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

This comment has been minimized.

Member

jimmyfrasche commented May 18, 2018

I like that.

@rsc

This comment has been minimized.

Contributor

rsc commented May 21, 2018

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

@rsc rsc changed the title from proposal: x/tools/cmd/godoc: create table of contents from headings in package overview to x/tools/cmd/godoc: create table of contents from headings in package overview May 21, 2018

@rsc rsc modified the milestones: Proposal, Unreleased May 21, 2018

@dsnet

This comment has been minimized.

Member

dsnet commented May 21, 2018

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

This comment has been minimized.

gopherbot commented May 21, 2018

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

@jimmyfrasche

This comment has been minimized.

Member

jimmyfrasche commented May 21, 2018

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

@rsc

This comment has been minimized.

Contributor

rsc commented Jun 4, 2018

Ping @griesemer to find reviewer.

@agnivade

This comment has been minimized.

Member

agnivade commented Sep 19, 2018

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

@dsnet

This comment has been minimized.

Member

dsnet commented Sep 19, 2018

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

This comment has been minimized.

Member

agnivade commented Sep 19, 2018

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

This comment has been minimized.

Contributor

spf13 commented Sep 19, 2018

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

This comment has been minimized.

Member

agnivade commented Sep 19, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment