go101 / golds Goto Github PK

View Code? Open in Web Editor NEW

584.0 16.0 28.0 1.3 MB

An experimental Go local docs server/generator and code reader implemented with some fresh ideas.

Home Page: https://go101.org/apps-and-libs/golds.html

License: MIT License

Go 100.00%

go golang tool docviewer codereader docgenerator

golds's Introduction

Go 101 is a series of books on Go programming. Currently, the following books are avaliable:

Go (Fundamentals) 101, which focuses on Go syntax/semantics (except custom generics related) and all kinds of runtime related things.
Go Generics 101, which explains Go custom generics in detail.
Go Optimizations 101, which provides some code performance optimization tricks, tips, and suggestions.
Go Details & Tips 101, which collects many details and provides several tips in Go programming.

These books are expected to help gophers gain a deep and thorough understanding of Go and be helpful for both beginner and experienced Go programmers.

To get latest news of Go 101 books, please follow the official twitter account @zigo_101.

Install, Update, and Read Locally

If you use Go toolchain v1.16+, then you don't need to clone the project respository:

### Install or update.

$ go install go101.org/go101@latest

### Read. (GOBIN path, defaulted as GOPATH/bin, should be set in PATH)

$ go101
Server started:
   http://localhost:55555 (non-cached version)
   http://127.0.0.1:55555 (cached version)

If you use Go toolchain v1.15-, or you would make some modifications (for contribution, etc.):

### Install.

$ git clone https://github.com/go101/go101.git

### Update. Enter the Go 101 project directory (which
# contains the current `README.md` file), then run

$ git pull

### Read. Enter the Go 101 project directory, then run

$ go run .
Server started:
   http://localhost:55555 (non-cached version)
   http://127.0.0.1:55555 (cached version)

The start page should be opened in a browser automatically. If it is not opened, please visit http://localhost:55555.

Options:

-port=1234
-theme=light # or dark (default is light)

Some HTML files are generated from their corresponding markdown files. If a markdown file is modified, we can run go run . -gen to synchronize its corresponding HTML file.

Contributing

Welcome to improve Go 101 by:

Submitting corrections for all kinds of mistakes, such as typos, grammar errors, wording inaccuracies, description flaws, code bugs and broken links.
Suggesting interesting Go related contents.

Current contributors are listed on this page.

Translations are also welcome. Here is a list of the ongoing translation projects:

中文版

License

Please read the LICENSE for more details.

golds's People

Contributors

Stargazers

Watchers

golds's Issues

panic: should not

> golds -gen -dir=generated -nouses ./...
panic: should not

goroutine 1869 [running]:
go101.org/golds/internal/server.(*docServer).tryRetrievingWorkdingDirectoryModuleInfo(0xc00015a000, 0xc01a07b200, 0x0?)
        D:/Desktop/golds-develop/internal/server/info_module.go:638 +0x13b8
go101.org/golds/internal/server.(*docServer).tryToCompleteModuleInfo(0x0?, 0x0?, 0x0?)
        D:/Desktop/golds-develop/internal/server/info_module.go:301 +0xc5
go101.org/golds/internal/server.(*docServer).analyze.func3.1(0x0?)
        D:/Desktop/golds-develop/internal/server/server.go:303 +0x25
go101.org/golds/code.(*CodeAnalyzer).confirmPackageModules.func1()
        D:/Desktop/golds-develop/code/code-parse.go:717 +0x54
created by go101.org/golds/code.(*CodeAnalyzer).confirmPackageModules in goroutine 1
        D:/Desktop/golds-develop/code/code-parse.go:715 +0x17a6

https://go101.org/apps-and-libs/golds.html

Cannot run the command: gold: error: cannot open ./...: No such file or directory

Hi,

I've followed the documentation to obtain gold using go get but once I try to run it I getting some errors:

$ export GO111MODULE=on
$ gold std  
gold: error: cannot open std: No such file or directory
$ gold ./...    
gold: error: cannot open ./...: No such file or directory
$ go version    
go version go1.14.7 linux/amd64

I'm trying to see documentation of this package, v2 branch.

Can you help me?

it doesn't seem to see submodules

I use submodules a lot, and by that I mean nested go.mod in the same git repository following what some people calls a MonoRepo.

unfortunately if I run golds -allow-network-connection -port 6060 -v . at a checkout of https://github.com/darvaza-proxy/slog for example, handlers/*/go.mod are ignored.

suggestions?

Make the image footer optional

This is a very cool package.

It would be a lot easier to adopt if you make the footer(twitter/wechat) optional.

Better yet, provide a config for user to either turn off the footer or customize their own during deployment.

On Windows, fail to auto choose server port if the preferred port is used.

feature request: use a configuration file for generation output settings

Possible future options:

custom footer
custom themes
custom translations
don't generate for dependencies and link dependency resources to go.dev
...

Options might be output format (html | json) specific.

Run golds command

I cannot get to run golds, or maybe I just didn't understand how to do it.

On my projects directory:

I set the go111module environment variable as on
I run "go get -u go101.org/golds" and everything seems fine.

Now if I run the command "golds ." I get the error "command not found: golds".

Am I missing something? Thank you in advance.

Option to omit source code all together

In very large repositories, I don't really want to include the source code again, I'd rather just link to the original source code files.

I realise this will require some level of heuristics for different source control hosters like GitHub, GitLab, etc.

panic with 0.5.0

With the latest version I get a panic when I try to generate the docs:

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x50 pc=0x8b6138]

goroutine 3864 [running]:
go101.org/golds/internal/server.(*docServer).WriteAstType(0xc0000c4000, 0xc028a42190, {0xa979a8?, 0xc01e321b20?}, 0xc022881980, 0xc022881980, 0x2?, 0xa3?, 0x0)
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2407 +0x1b8
go101.org/golds/internal/server.(*docServer).writeResourceIndexHTML(0xc0000c4000, 0xc028a42190, 0xc022881980, {0xa99160, 0xc022abe620?}, 0x1, 0x1, 0x0)
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2015 +0xc1c
go101.org/golds/internal/server.(*docServer).buildPackageDetailsPage.func8()
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:444 +0x45
go101.org/golds/internal/server.writeFoldingBlock(0xa91364?, {0xc01e30b680, 0xd}, {0x9b2462, 0x7}, {0x9afac0, 0x4}, 0x0, 0xc005717ae8, 0xc005717c00)
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2748 +0x202
go101.org/golds/internal/server.(*docServer).buildPackageDetailsPage(0xc0000c4000, {0xa97fa8?, 0xc01a5a0000}, 0xc027a45e00)
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:442 +0x1054
go101.org/golds/internal/server.(*docServer).packageDetailsPage(0xc0000c4000, {0xa97fa8, 0xc01a5a0000}, 0x9b1b62?, {0xc023a75185, 0x6})
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:60 +0x2ee
go101.org/golds/internal/server.(*docServer).ServeHTTP(0xc0000c4000, {0xa97fa8, 0xc01a5a0000}, 0xc0242ca100)
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/server.go:212 +0x838
go101.org/golds/internal/server.GenDocs.func1({0xc023a75180, 0xb})
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:523 +0x145
go101.org/golds/internal/server.GenDocs.func3()
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:572 +0xb1
created by go101.org/golds/internal/server.GenDocs
        /home/paul/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:565 +0x5b2

Support Go 1.19 godoc formatting

See ~~golang/go#51028~~ golang/go#51082. It seems like this should mostly be a matter of updating some dependencies, but I don't know for sure.

Escaping HTML tags

There is js code in code example "_autoescaping" that is actually executing on the page https://docs.go101.org/std/pkg/html/template.html and showing alert with message "you have been pwned".

Feature request: show doc summary under each symbol

Having a one-line summary for each symbol displayed under the symbol would be very useful, as when browsing API's it's often difficult to tell what a type/function will do without reading the doc. eg. Instead of

func MyFunc()

It would display:

func MyFunc()
  This function does something really awesome.

Feature request: show package documentation by default

It seems very strange to me that when I navigate to the documentation for a package, I don't see the actual documentation. I have to hunt and expand a tiny d. Please consider showing the documentation at the top, similar to how godoc and go.pkg.dev work.

Panic with Go 1.20.3

First time user of golds and wanted to check it out, trying to find a way to create docs then publish them to a separate web server.

Sadly, just running the basics is not working when merely throwing it at our source tree:

$ go version                                                                                                                                                                                                                                                               go version go1.20.3 darwin/arm64
$ go install go101.org/golds@latest
go: downloading go101.org/golds v0.6.4
go: downloading golang.org/x/net v0.7.0
go: downloading golang.org/x/text v0.7.0
go: downloading golang.org/x/tools v0.6.0
go: downloading golang.org/x/mod v0.8.0
go: downloading golang.org/x/sys v0.5.0
$ golds ./...                                                                                                                                                                                                                                                              2 ↵
[Analyzing] Start analyzing ...
[Analyzing] Preparation done: 796.631166ms
[Analyzing] 2 files parsed: 222.25µs
[Analyzing] 4 files parsed: 302.292µs
[Analyzing] 8 files parsed: 583.084µs
[Analyzing] 16 files parsed: 1.30475ms
[Analyzing] 32 files parsed: 2.727459ms
[Analyzing] 64 files parsed: 3.980084ms
[Analyzing] 128 files parsed: 8.191792ms
[Analyzing] 256 files parsed: 19.165959ms
[Analyzing] 512 files parsed: 152.815792ms
[Analyzing] 1024 files parsed: 252.670084ms
[Analyzing] 2048 files parsed: 563.152209ms
[Analyzing] All 2400 files are parsed: 993.025042ms
[Analyzing] Collected 423 packages: 487.663375ms
[Analyzing] Collected 57 modules: 515.903417ms
[Analyzing] Sorted packages by dependency relations: 295.583µs
[Analyzing] Collected Source Files: 580µs
[Analyzing] Collected declarations: 36.28525ms
panic: unnamed interface should have collected direct selectors now. &code.TypeInfo{TT:(*types.Interface)(0x14021a4b810), Exprs:[]ast.Expr(nil), Underlying:(*code.TypeInfo)(0x14021b122c0), TypeName:(*code.TypeName)(nil), Instantiated:(*code.InstantiatedInfo)(nil), Implements:[]code.Implementation(nil), ImplementedBys:[]*code.TypeInfo(nil), Aliases:[]*code.TypeName(nil), Underlieds:[]*code.TypeName(nil), DirectSelectors:[]*code.Selector(nil), EmbeddingFields:0, AllMethods:[]*code.Selector(nil), AllFields:[]*code.Selector(nil), AllSelectors:map[string]*code.Selector(nil), AsTypesOf:[]code.ValueResource(nil), AsInputsOf:[]code.ValueResource(nil), AsOutputsOf:[]code.ValueResource(nil), attributes:0x20000000, index:0x8948, counter:0x8949}

goroutine 38 [running]:
go101.org/golds/code.(*CodeAnalyzer).collectSelectorsForInterfaceType(0x14014a61c18?, 0x14021b122c0, 0x0, 0x8949, 0x14014a61c20)
	/Users/myuser/go/pkg/mod/go101.org/[email protected]/code/code-analyse.go:1118 +0x7dc
go101.org/golds/code.(*CodeAnalyzer).collectSelectors(0x14000156000)
	/Users/myuser/go/pkg/mod/go101.org/[email protected]/code/code-analyse.go:937 +0xbc
go101.org/golds/code.(*CodeAnalyzer).AnalyzePackages(0x14000156000, 0x14014a61dd0)
	/Users/myuser/go/pkg/mod/go101.org/[email protected]/code/code-analyse.go:59 +0x1c8
go101.org/golds/internal/server.(*docServer).analyze(0x140041a2000, {0x140000b8010, 0x1, 0x1}, {{0x104c1a3d7, 0x6}, {0x14000028025, 0xb}, 0x0, 0x0, ...}, ...)
	/Users/myuser/go/pkg/mod/go101.org/[email protected]/internal/server/server.go:348 +0x43c
go101.org/golds/internal/server.Run.func1()
	/Users/myuser/go/pkg/mod/go101.org/[email protected]/internal/server/server.go:135 +0x9c
created by go101.org/golds/internal/server.Run
	/Users/myuser/go/pkg/mod/go101.org/[email protected]/internal/server/server.go:134 +0x5d8

Any suggestions to further investigate this?

$ golds toolchain

works, for comparison. The code being analysed is working, compiling, testable and running.

feature request: displaying docs of struct exported methods

I personally use golds as a more informative alternative of godoc, and its code navigation feature has made it really convenient to inspect libraries.

However I find it a bit bothersome that I need to navigate to a struct export method's implementation just to view its docs.

Having the docs next to the method signature (foldable or not) or as a tooltip displayed when hovering over the method signature would be helpful.

Feature request: watch mode

golds right now does not pick up changes made in the packages it has already parsed, even if we refresh the browser. Please consider adding a watch mode to reflect the changes on the filesystem. I think it would be very helpful for package authors.

feature request: support different output formats

comes from golang/go#41744

Allow passing a list of packages to be included

I am looking for something similar to how the std mode works but where i have a number of related repos that i would like parsed together into one generated output.

Example: golds -wdpkgs-listing=promoted x.y.z/myapp1 x.y.z/myapp2 x.y.z/myapp3 x.y.z/myappN

where all of the packages related to the list provided are included in the promoted.

x.y.z/myapp1 
x.y.z/myapp1/cmd/bin 
x.y.z/myapp2
x.y.z/myapp2/internal/foo
x.y.z/myapp2/internal/bar 
x.y.z/myapp3
x.y.z/myapp3/pkg/baz
x.y.z/myappN

...other packages...

Panic with cold mod cache

When running golds on go.pact.im/x source code with “cold” local modules cache, golds panics on first attempt.

$ go clean -modcache
$ golds -dir=build/doc -gen -silent -footer=simple -wdpkgs-listing=solo all
panic: runtime error: index out of range [0] with length 0

goroutine 1 [running]:
go101.org/golds/code.(*CodeAnalyzer).confirmPackageModules(0xc0000d0000, {0xc000128060?, 0x1?, 0x3?}, 0x0, {{0xc00013c260, 0x16}, {0xc00013c260, 0x1a}, {0xc00013c260, ...}, ...}, ...)
        go101.org/[email protected]/code/code-parse.go:544 +0x1e6a
go101.org/golds/code.(*CodeAnalyzer).ParsePackages(0xc0000d0000, 0xc00010c420, 0xc000146000?, {{0xc00013c260, 0x16}, {0xc00013c260, 0x1a}, {0xc00013c260, 0x1e}, {0xc000134000, ...}}, ...)
        go101.org/[email protected]/code/code-parse.go:466 +0x19b3
go101.org/golds/internal/server.(*docServer).analyze(0xc000146000, {0xc000128060, 0x1, 0xa92ad8?}, {{0x9ac4ba, 0x6}, {0x0, 0x0}, 0x0, 0x0, ...}, ...)
        go101.org/[email protected]/internal/server/server.go:295 +0x43c
go101.org/golds/internal/server.GenDocs({{0x9ac4ba, 0x6}, {0x0, 0x0}, 0x0, 0x0, 0x0, 0x0, 0x0, {0x9aa68c, ...}, ...}, ...)
        go101.org/[email protected]/internal/server/tool_gen-docs.go:506 +0x377
go101.org/golds/internal/app.run()
        go101.org/[email protected]/internal/app/run.go:234 +0xf65
go101.org/golds/internal/app.Main(...)
        go101.org/[email protected]/internal/app/run.go:33
main.main()
        go101.org/[email protected]/main.go:10 +0x53

And subsequent run succeeds. 🙃

$ golds -dir=build/doc -gen -silent -footer=simple -wdpkgs-listing=solo all
tool_gen-docs.go:630: Docs are generated in build/doc.
tool_gen-docs.go:639: Run the following command to view the docs:
tool_gen-docs.go:640:   golds -dir=build/doc

footer option doesn't work

version Golds v0.6.7
According to help:
-footer-showing=verbose+qrcode|verbose|simple|none
Specify how page footers should be shown.
Available values (default is verbose+qrcode):
* none: show nothing.
* simple: show Golds version only.
* verbose: also show Golds author.
promotion info.
* verbose+qrcode: include verbose content
and a qr-code.
I tried
-footer-showing=none
then
-footer-showing=simple
It doesn't work.
Always shows verbose+qrcode

Option to avoid outputting to a subdirectory

Or preferably, just don't output to a subdirectory at all - the user already controls the flag, so they can specify whatever directory they prefer.

When I use -dir=docs I expect that the docs will actually be in that directory, not a subdirectory. This is unintuitive as-is, but also causes actual problems when trying to deploy docs through CI because the general expectation is that the CI pipeline can point to a static directory and just push it up to the documentation site. As the sub-directory changes on each invocation, this expectation is broken.

Incorrect file names of generated HTML files

Some generated HTML files have a * in their file name which is not possible on Windows.

e.g. `docs/dep/github.com/ORGANISATION*34f8c/blahblah/test.html'

if the docs are committed to github pages for rendering, the following happens on Windows when checking out the code

"C:\Program Files\Git\bin\git.exe" checkout --progress --force -B master refs/remotes/origin/master
Error: error: invalid path 'docs/dep/github.com/ORGANISATION*34f8c/blahblah/test.html'
Error: The process 'C:\Program Files\Git\bin\git.exe' failed with exit code 128

expand all

this page for example:

https://docs.go101.org/std/pkg/bytes.html

every single item is collapsed. especially for the examples, it would be helpful for some button and/or method to expand all of the entries.

Golds v0.4.2 does not find go files

I ran the same command golds -gen -wdpkgs-listing=solo -only-list-exporteds -dir=../docs -nouses ./... with Golds 0.4.1 and 0.4.2.
It works perfectly with Golds 0.4.1. However, with the latest version I get the following error:

-: no Go files in <...>
code-parse.go:301: exit for above errors.

If you are sure that the code should compile okay, and
you just upgraded your Go toolchain to a new Go version,
then please rebuild Golds with the following command.

        go install go101.org/golds@latest

Feature request: skip standard packages

golds has no option to create help for selected package only (not including standard packages).
Could you please think of adding such an option?
I mean, index.html links only package itself, not all imports, and of course the html files are generated for package only.

docco/pycco style side by side code and annotated comments

Can we have a code view inspired by docco?
The implementation can be a theme or different view, whatever makes sense.

Key ideas:

Process markdown in comments
Show comment and code side by side, the result becomes more readable.

Examples:

golds renders much more powerful view for code navigation than docco (and it's ports). If we have this additional feature, I believe it can be a powerful tool for code reading enthusiasts who also like to produce annotated source code (as artefacts) of popular/well-written codebases (like this or this, but much better).

How to generate docs for project only?

How to restrict golds to generate the HTML docs for just the current project?

$ ls -Altr
total 96
-rw-r--r--   1 user  wheel    22B Dec 30 15:17 .gitignore
-rw-r--r--   1 user  wheel   1.1K Dec 30 15:17 LICENSE
-rw-r--r--   1 user  wheel    10K Dec 30 15:17 README.md
-rw-r--r--   1 user  wheel    12K Dec 30 15:17 TODO.md
drwxr-xr-x   8 user  wheel   256B Dec 30 15:17 code/
-rw-r--r--   1 user  wheel   126B Dec 30 15:17 go.mod
-rw-r--r--   1 user  wheel   2.7K Dec 30 15:17 go.sum
drwxr-xr-x   3 user  wheel    96B Dec 30 15:17 gocore/
drwxr-xr-x   3 user  wheel    96B Dec 30 15:17 godoge/
drwxr-xr-x   3 user  wheel    96B Dec 30 15:17 gold/
drwxr-xr-x   6 user  wheel   192B Dec 30 15:17 internal/
-rw-r--r--   1 user  wheel    85B Dec 30 15:17 main.go
drwxr-xr-x  12 user  wheel   384B Dec 30 15:17 .git/


$ golds -emphasize-wdpkgs -compact -gen -dir=.generated .
...

Support dark theme

I think it's nice to have to browsing go docs in dark theme!

Docs don't work for Case Insensitive File Systems (OS X, Windows)

My colleague generated docs using this project and checked it into git repo. The generated files contained many files with the same name but with different cases. For example the generator created the files:

docs/imp/github.com/golang/protobuf/jsonpb.AnyResolver.html
docs/imp/github.com/golang/protobuf/jsonpb.anyResolver.html

When I attempted to clone this repo on an OS X laptop I got the following errors:

warning: the following paths have collided (e.g. case-sensitive paths
on a case-insensitive filesystem) and only one from the same
colliding group is in the working tree:

Even setting git config core.ignorecase did not fix the issue. Understandably it would be better if these file systems respected case, but that's unlikely to change anytime in the future.

Is it possible to change the naming of files to account for case insensitive file systems?

panic: writeExternalSourceCodeLink error: buildExternelSourceLink: source file github.com/PagerDuty^9f750/go-pagerduty/client.go not found

This started happening when we upgraded from go-1.16 to go-1.17:

panic: writeExternalSourceCodeLink error: buildExternelSourceLink: source file github.com/PagerDuty^9f750/go-pagerduty/client.go not found

goroutine 39437 [running]:
go101.org/golds/internal/server.buildPageHref({{0x1034496a3, 0x3}, {0x14007da3830, 0x2c}}, {{0x1034496ca, 0x3}, {0x1409d8a7480, 0x31}}, 0x140b4119630, {0x0, ...}, ...)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:357 +0xbd4
go101.org/golds/internal/server.writeSrouceCodeLineLink(0x140b4119630, 0x140890cb8c0, {{0x14008fcbce0, 0x66}, 0x793, 0x4a, 0x2}, {0x140ad4fe89a, 0x2}, {0x0, ...})
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:1662 +0x228
go101.org/golds/internal/server.(*docServer).writeMethodForListing(0x14000138000, 0x140b4119630, 0x140890f0840, 0x140725167e0, 0x1409c3c7650, 0x1, 0x0)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:1790 +0x25c
go101.org/golds/internal/server.(*docServer).buildPackageDetailsPage.func9.4.1(0x14009593ac8, 0x1400959356f, 0x140095935b0, 0x140b4119630, 0x14000138000, 0x1400aab04b0, 0x1409c129900)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:506 +0x124
go101.org/golds/internal/server.(*docServer).buildPackageDetailsPage.func9.4()
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:526 +0x1ec
go101.org/golds/internal/server.writeFoldingBlock(0x140b4119630, {0x1402e5e4880, 0xa}, {0x10344c999, 0x7}, {0x10344a657, 0x5}, 0x0, 0x14009593798, 0x14009593800)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2645 +0x2cc
go101.org/golds/internal/server.(*docServer).buildPackageDetailsPage.func9()
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:487 +0x340
go101.org/golds/internal/server.writeFoldingBlock(0x140b4119630, {0x1402e5e4880, 0xa}, {0x10344c483, 0x7}, {0x103449b29, 0x4}, 0x0, 0x14009593b38, 0x14009593bd8)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2645 +0x2cc
go101.org/golds/internal/server.(*docServer).buildPackageDetailsPage(0x14000138000, {0x1035e4ad8, 0x140af97e150}, 0x1400aab04b0)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:414 +0xefc
go101.org/golds/internal/server.(*docServer).packageDetailsPage(0x14000138000, {0x1035e4ad8, 0x140af97e150}, 0x14064ea2500, {0x140c4132145, 0x2c})
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:60 +0x30c
go101.org/golds/internal/server.(*docServer).ServeHTTP(0x14000138000, {0x1035e4ad8, 0x140af97e150}, 0x14064ea2500)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/server.go:212 +0x898
go101.org/golds/internal/server.GenDocs.func1({0x140c4132140, 0x31})
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:522 +0x9c
go101.org/golds/internal/server.GenDocs.func3(0x14064ea6000, 0x14028bc8060)
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:571 +0x8c
created by go101.org/golds/internal/server.GenDocs
	/Users/aat/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:564 +0x4f0

cannot get/install on go 1.17

Using go version go1.17.11 linux/amd64

# go install go101.org/golds@latest
go: downloading go101.org/golds v0.5.1
go: downloading golang.org/x/net v0.0.0-20220225172249-27dd8689420f
go: downloading golang.org/x/tools v0.1.10
go: downloading golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e
go: downloading golang.org/x/mod v0.6.0-dev.0.20220106191415-9b9b3d81d5e3
# go101.org/golds/internal/server
/root/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2408:29: undefined: types.TypeParam
note: module requires Go 1.18

# go get -u go101.org/golds
go get: installing executables with 'go get' in module mode is deprecated.
        To adjust and download dependencies of the current module, use 'go get -d'.
        To install using requirements of the current module, use 'go install'.
        To install ignoring the current module, use 'go install' with a version,
        like 'go install example.com/cmd@latest'.
        For more information, see https://golang.org/doc/go-get-install-deprecation
        or run 'go help get' or 'go help install'.
# go101.org/golds/internal/server
/root/go/pkg/mod/go101.org/[email protected]/internal/server/page_package-details.go:2408:29: undefined: types.TypeParam
note: module requires Go 1.18

could not import C

root@9f31100ac3ac:/project# golds -gen -dir=/root/w .
/project/cbrotli/cgo.go:13:8: could not import C (no metadata for C)
exit for above errors

Can I skip a specified subpackage when generating doc for the project?

module path is mismatching

go version: 1.13.7

$ go get -u go101.org/gold      
go: extracting go101.org/gold v0.1.5
go get: go101.org/[email protected]: parsing go.mod:
        module declares its path as: go101.org/golds
                but was required as: go101.org/gold

Generate single page

Hi, thank for the golds it's amazing. I was looking for a param, where I can generate docs for few packages (with a common root, but probably it's not so important) but haven't found.

Is there a chance that this param can be added? Thanks!

package level godoc missing

question about godoc, in my file, dataprov.go, I have package level godoc like this:

// Package dataprov holds the data provenance logic which is essentially
// used to identify each data source uniquely with a generated ID
// that is passed with all processed data so users can track data back
// to its source
package dataprov

however, when I generate and few the docs for this package I'm not seeing the package godoc
at all...question, is package level godoc text supposed to be present in the generated page?

thanks.

Panic with go 1.21

When I use golds with go 1.21, I always get: panic: ParsePackages: dependency package cmp not found

Here is a one-liner to reproduce the issue: docker run --rm -it golang:1.21 bash -c "git clone https://github.com/go101/golds.git && cd golds && go run . ."

Show version tag of package?

I was wondering if it was possible to show multiple versions of a package.

I'm looking to set up an internal package docs service for our company. Our users may be developing using different versions of a package. It would be nice to be able to show docs for multiple versions of a package. We manage versions in the common idomatic manner of using git tags of format "v0.0.1" etc.

I realize that showing all versions would be difficult as you'd have to be git aware and loop through all history of git tags in a package dir that's been identified as a git repo.

Maybe some opinionation of how someone could host multiple versions of a package would be nice. That way we could package up the versions of a package as artifacts and export to a standard format that the GUI is aware of. E.g., if golds is serving a directory of packages and it sees the following contents:

mypackage_v0.0.1_
mypackage_v0.0.2_
otherpackage_v0.3.4_

The GUI knows to strip the underscores and parse the version and inject into the GUI somehow. Obviously pkg.go.dev is version aware so you could easily generate the links to the specific versions.

Package mypackage (v0.0.1)

Import Path
	[github.com/myorg/mypackage](http://localhost:56789/#pkg-github.com/myorg/mypackage) (on [go.dev](https://pkg.go.dev/github.com/myorg/[email protected]))

...

Package mypackage (v0.0.2)

Import Path
	[github.com/myorg/mypackage](http://localhost:56789/#pkg-github.com/myorg/mypackage) (on [go.dev](https://pkg.go.dev/github.com/myorg/[email protected]))

...

Package otherpackage (v0.3.4)

Import Path
	[github.com/myorg/mypackage](http://localhost:56789/#pkg-github.com/myorg/otherpackage) (on [go.dev](https://pkg.go.dev/github.com/myorg/[email protected]))

Just thinking of ways to do it without a ton of git work.

Selectors not collected from embedding instantiated types

just a reminder

panic: runtime error: slice bounds out of range [2668:2667]

Project involved: https://github.com/cybertec-postgresql/pg_timetable (v4_dev branch)

Command line:

golds.exe -gen -nouses -only-list-exporteds .

Call stack:

tool_gen-docs.go:488: Generated src/github.com/cybertec-postgresql/pg_timetable/internal/pgengine/migration.go.html (size: 37847).
panic: runtime error: slice bounds out of range [2668:2667]

goroutine 4022 [running]:
go101.org/golds/internal/server.(*astVisitor).buildConfirmedLines(0xc01220d500, 0x51, 0x0, 0x0)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:717 +0x32a
go101.org/golds/internal/server.(*astVisitor).buildIdentifier(0xc01220d500, 0xc0002f3b40, 0x40, 0xa73, 0x51, 0x2, 0xc0002f3b40, 0x40, 0xa76, 0x51, ...)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:795 +0x99
go101.org/golds/internal/server.(*astVisitor).handleIdent(0xc01220d500, 0xc0099bf420)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:1426 +0x4c5
go101.org/golds/internal/server.(*astVisitor).Visit(0xc01220d500, 0xfdd7d0, 0xc0099bf420, 0xc018975368, 0xe0d29e)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:1231 +0x867
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdd7d0, 0xc0099bf420)
        C:/Program Files/Go/src/go/ast/walk.go:52 +0x6a
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdda00, 0xc0090fb2c0)
        C:/Program Files/Go/src/go/ast/walk.go:110 +0x21e5
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdda00, 0xc0090fb2d8)
        C:/Program Files/Go/src/go/ast/walk.go:110 +0x21e5
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdd488, 0xc003b717c0)
        C:/Program Files/Go/src/go/ast/walk.go:136 +0xfa5
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdd640, 0xc011f60f80)
        C:/Program Files/Go/src/go/ast/walk.go:196 +0x1a25
go/ast.walkStmtList(0xfda9e0, 0xc01220d500, 0xc012106100, 0xa, 0x10)
        C:/Program Files/Go/src/go/ast/walk.go:32 +0xa5
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdd438, 0xc014cda9c0)
        C:/Program Files/Go/src/go/ast/walk.go:224 +0x1988
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdd708, 0xc014cda9f0)
        C:/Program Files/Go/src/go/ast/walk.go:344 +0xd06
go/ast.walkDeclList(0xfda9e0, 0xc01220d500, 0xc0123d6d00, 0x8, 0x8)
        C:/Program Files/Go/src/go/ast/walk.go:38 +0xa5
go/ast.Walk(0xfda9e0, 0xc01220d500, 0xfdd6b8, 0xc0123d6f80)
        C:/Program Files/Go/src/go/ast/walk.go:353 +0x2466
go101.org/golds/internal/server.(*docServer).analyzeSoureCode(0xc0000d2000, 0xc01cecbc75, 0x3e, 0xc01cecbcb4, 0xc, 0x0, 0x0, 0x0)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:1838 +0xe71
go101.org/golds/internal/server.(*docServer).sourceCodePage(0xc0000d2000, 0xfe38c0, 0xc01105e000, 0xc015c26200, 0xc01cecbc75, 0x3e, 0xc01cecbcb4, 0xc)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/page_source-code.go:70 +0x2e6
go101.org/golds/internal/server.(*docServer).ServeHTTP(0xc0000d2000, 0xfe38c0, 0xc01105e000, 0xc015c26200)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/server.go:217 +0xe99
go101.org/golds/internal/server.GenDocs.func1(0xc01cecbc70, 0x50, 0xc0246cfe50, 0x1, 0x3, 0x0, 0x0)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:397 +0xa5
go101.org/golds/internal/server.GenDocs.func3(0xc015c2a000, 0xc007f9a060)
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:445 +0xeb
created by go101.org/golds/internal/server.GenDocs
        C:/Users/pasha/go/pkg/mod/go101.org/[email protected]/internal/server/tool_gen-docs.go:438 +0x35d

suggestion: make style similar to godoc

It would be great to have a style same, or very similar, as godoc. Most people are familiar with that style and I faced an issue when I had to explain to people that the exported methods are expandable and they can see more documentation after clicking a plus sign.

godoc

How is this different from the godoc local webserver functionality that came with go before they removed it?

Support include/exclude filters

We have a large internal codebase and I'd love to be able to use Gold to generate static documentation for it, but it's currently

However, we have a large number of generated proto files in addition to >7000 vendored files. Docs for these are both noisy and unnecessary, as they're either public or generated. It would be great to be able to exclude packages, as well as specify the exact packages to generate docs for.

Alternatively it would also work if there were an option to disable generating docs transitively, so I could just pass the exact list of packages to generate docs for, eg. gold $(go list ./... | grep -v /protos/)

For reference, Gold currently takes 8 minutes to run on this repo and generates 2GB of docs.