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.

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: sort package list into stdlib and GOPATH #3305

Closed
adg opened this issue Mar 13, 2012 · 24 comments

Comments

Projects
None yet
@adg
Copy link
Contributor

commented Mar 13, 2012

Brad: "I'd really like to see the standard library by itself, or at least broken up
by itself at the top of the page, with third-party GOPATH stuff at the bottom."

Russ: "If you really wanted to, you could do something like
http://golang.org/cl/5797067 But I am not sure it's such a good idea"

Brad: "Sounds like a great idea. Much prettier. What's the downside?"

Russ: "I have used systems with 'mostly sorted' lists before, and the convenience
always seems to give way to confusion, because people think they _are_ sorted and then
can't find things."

Robert: "Can we have different modes for looking at it?"

Brad: "The default is all that matters. There's already a flat mode (which I
prefer), but I can never remember how to get to it without looking up the source, which
I'm always too lazy to do. You could argue for mode-switching links, but therein lies
craziness."
@rsc

This comment has been minimized.

Copy link
Contributor

commented Sep 12, 2012

Comment 1:

Maybe sorting is the wrong word and that what we should really do is group by root.
@bradfitz

This comment has been minimized.

Copy link
Member

commented Sep 12, 2012

Comment 2:

FWIW this continues to bother me.  Grouping by root would be fine.  I'd be happen even
with two groups:
standard library $GOROOT first (bounded set, with short names), followed by all $GOPATHs
merged together and sorted (a huge set with longer names)
@rsc

This comment has been minimized.

Copy link
Contributor

commented Sep 12, 2012

Comment 3:

Labels changed: added go1.1maybe.

@robpike

This comment has been minimized.

Copy link
Contributor

commented Mar 7, 2013

Comment 5:

Labels changed: removed go1.1maybe.

@adg

This comment has been minimized.

Copy link
Contributor Author

commented Mar 18, 2013

Comment 6:

Labels changed: added godoc.

@gopherbot

This comment has been minimized.

Copy link

commented Apr 1, 2013

Comment 7:

As a new user of the language, starting to build up my own little library packages as I
build more complicated programs, and starting to look at packages written by third
parties, I definitely would like a way for godoc to show somewhat more clearly which
packages are "core" libraries and which are third party.
Being able to have the list-of-packages stay as a sidebar when viewing the individual
package godoc pages would also be a win -- at least as somebody new to the language and
libraries I find myself surfing around between the list of all packages and individual
packages a lot, as I figure out what's where.
@adg

This comment has been minimized.

Copy link
Contributor Author

commented Jun 26, 2013

Comment 8:

Issue #5784 has been merged into this issue.

@mewmew

This comment has been minimized.

Copy link
Contributor

commented Aug 1, 2013

Comment 9:

issue #5571 is related to this issue and may be solved with a unified solution. For
instance it would be possible to include three sections in the package listing, namely:
* Standard repositories
* Sub-repositories
* Third party repositories
@mewmew

This comment has been minimized.

Copy link
Contributor

commented Aug 1, 2013

Comment 10:

Sorry I meant issue #5561.
@pebbe

This comment has been minimized.

Copy link
Contributor

commented Aug 3, 2013

Comment 11:

If you have many non-standard packages installed, it gets unwieldy to navigate.
I would like standard packages and each part of GOPATH to have its own section, and also
be able to collapse/expand each level. This idea:
http://pkleiweg.home.xs4all.nl/go/godoc-demo.html
@rsc

This comment has been minimized.

Copy link
Contributor

commented Nov 27, 2013

Comment 12:

Labels changed: added go1.3maybe.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 4, 2013

Comment 13:

Labels changed: added release-none, removed go1.3maybe.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 4, 2013

Comment 14:

Labels changed: added repo-tools.

@paulswanson

This comment has been minimized.

Copy link

commented Mar 2, 2015

@adg I'd like to add a practical observation. I find the headings misleading.

Currently, (go1.4.2), $GOPATH imports are alphabetically intermingled with packages from the standard library under a heading "Standard library". Further down the page there is a heading "Other packages" where I'd naturally expect my imports to be listed. It's not a clear structure.

I feel that separating Standard Library documentation from GOPATH would make more sense, but even if it's deemed not, the headings need to reflect the structure more accurately.

@adg

This comment has been minimized.

Copy link
Contributor Author

commented Mar 3, 2015

@paulswanson I agree that the gopath packages should be in a separate list to the standard library.

@paulswanson

This comment has been minimized.

Copy link

commented Mar 9, 2015

@adg, the more I use godoc the more it's ticking me off. What's required to move this forward? Is this one a question of consensus and / or implementation? Cheers.

@adg

This comment has been minimized.

Copy link
Contributor Author

commented Mar 9, 2015

It's an implementation thing.

@rsc rsc added this to the Unplanned milestone Apr 10, 2015

@rsc rsc changed the title cmd/godoc: sort package list into stdlib and GOPATH x/tools/cmd/godoc: sort package list into stdlib and GOPATH Apr 14, 2015

@andradei

This comment has been minimized.

Copy link

commented Dec 26, 2017

It would be nice to have this worked on. A separation of Standard Library and GOPATH libraries would improve the godoc experience immensely.

Also, Merry Christmas and thank you for working on Go.

@agnivade

This comment has been minimized.

Copy link
Member

commented Jan 24, 2018

I will take a stab at it. I also like @pebbe's suggestion about collapsing/expanding items beyond a certain depth. Makes for a much cleaner UI.

@agnivade

This comment has been minimized.

Copy link
Member

commented Feb 2, 2018

I have brought it to a presentable state now. I have grouped them under 2 headers - Standard Library and Third Party, which are collapsible and expandable like in a package directory. This would make for a much more cleaner experience.

In collapsed form -
screenshot-2018-2-2 - the go programming language 1

Expanding the third part section -
screenshot-2018-2-2 - the go programming language 2

I will send a CL once the 1.11 tree opens.

@pebbe

This comment has been minimized.

Copy link
Contributor

commented Feb 2, 2018

When GOPATH has multiple parts, I would like to see each part have its own section

@agnivade

This comment has been minimized.

Copy link
Member

commented Feb 2, 2018

Hmm .. that is a bit non-trivial as it would involve more changes to the PageInfo struct to avoid looping multiple times through the DirList in the html template.

I think the current CL is a good start, and since the original issue was just about grouping it into GOROOT and GOPATH, its good to keep this to just that to avoid further complexity in the review.

Maybe it's best to tackle this in a separate issue.

@gopherbot

This comment has been minimized.

Copy link

commented Feb 21, 2018

Change https://golang.org/cl/95835 mentions this issue: godoc: group package home page list by root

@gopherbot

This comment has been minimized.

Copy link

commented Mar 18, 2018

Change https://golang.org/cl/101295 mentions this issue: godoc: cleanup package templates

@andybons andybons added the NeedsFix label Mar 19, 2018

gopherbot pushed a commit to golang/tools that referenced this issue Apr 10, 2018

godoc: cleanup package templates
Separate the templates of package root directory and other
directories. This removes several if-else conditions and
makes the template code much cleaner.

To be merged after CL 95835.

For golang/go#3305

Change-Id: I435441dbe214e4c89271483173df7c30a42ee28f
Reviewed-on: https://go-review.googlesource.com/101295
Run-TryBot: Andrew Bonventre <andybons@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>

@golang golang locked and limited conversation to collaborators Apr 10, 2019

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
You can’t perform that action at this time.