It is fairly trivial to compile a given Go version and run the doc server locally to search for an older API. But it would be nice if golang.org provided access to docs per release. One simple solution to this is to add an option to godoc to generate static docs on disk -- just a tree of static files (search would be disabled of course). Then docs for old versions could be made available somewhere in golang.org. One additional benefit is that projects that want to ship docs could generate the static files and provide the html files for download, or create pdfs, chms etc based on them. PS: I tried searching for a similar issue; sorry if this is a duplicate.
moraes
All 29 comments
This is being worked on, kinda. Now that godoc can run on App Engine, we'll be doing something like running different subdomains of golang.org for old releases. Andrew knows the details.
_Owner changed to @adg._
_Status changed to Accepted._
bradfitz
on 21 Oct 2011
To generate static docs, just run this command: godoc -http=localhost:8080 & wget -r -np http://localhost:8080/pkg/ We're working on providing online docs for older versions of Go.
adg
on 26 Oct 2011
I haven't thought about using wget. Nice. For those interested in this trick, here are some notes. First, edit robots.txt in the go root directory, and remove "Disallow: /". Otherwise only the index will be downloaded because wget respects robots.txt. Then start godoc pointing to the project path: godoc -path="/path/to/project" -http=:8080 And finally this a more complete command to get a working static docs, including static files and with proper links: wget -r -np -N -E -p -k http://localhost:8080/pkg/ -r : download recursive -np : don't ascend to the parent directory -N : don't retrieve files unless newer than local -E : add extension .html to html files (if they don't have) -p : download all necessary files for each page (css, js, images) -k : convert links to relative
moraes
on 31 Oct 2011
rsc
josharian
on 11 Oct 2013
I would also like godoc to be able to generate static docs. The proposed workaround (hosting all the files and wgeting it) works but it crawls the entire contents of your GOPATH, which is less than ideal because that then bloats the static docs incredibly.
I still want things like the builtins to link correctly to docs, so some incantation of go list to pull out the dependencies of the project would be ideal. Unfortunately, I can't just write a bash script to do this because using godoc -html path/to/package just returns the raw HTML without any CSS, and no JS to handle section expansion.
EDIT: Managed to do this in the end with a fairly noddy script.
Kegsay
on 2 Nov 2016
Change https://golang.org/cl/72890 mentions this issue: godoc/internal/render: add render package for text formatting
gopherbot
on 24 Oct 2017
As part of my work on #18342, I wrote simple static generator for godoc, that I realized is really well suited for resolving this issue. Is there any interest in including it's generated output in each release?
You can see statically generated docs at: https://static-hotlinks.digitalstatic.net/
dsnet
on 24 Oct 2017
As part of my work on #18342, I wrote simple static generator for godoc, that I realized is really well suited for resolving this issue. Is there any interest in including it's generated output in each release?
@dsnet Is this static generator available somewhere? I'd like to give it a try for hosting docs for a few packages.
ghost
on 6 Nov 2017
You can download the patch from CL/72890 and run render_docs.go directly.
dsnet
on 6 Nov 2017
Suggestion for those using this workaround, you may eventually want to add this to your wget command line: -X debug/pprof
joeldeaguero
on 19 Feb 2018
For the record, I went with Cheney's godoc2md tool: https://github.com/davecheney/godoc2md and it works perfectly. I feed the resulting markdown files into a static site generator like Hugo.
ghost
on 19 Feb 2018
I'd like to second supporting a static output of go doc without having to use other external tools like wget. I feel like https://github.com/davecheney/godoc2md solves this fairly well, but that tool is no longer being supported. I'd recommend adding markdown output to the go doc command.
The use case is fairly simple. When working on private packages or modules that can't be made public, it's nice to just bundle the docs in the repo as a README.md.
Linuturk
on 26 Feb 2019
As user, I'd like to express how "lost" I feel to generate a directory containing self contained documentation of a go project and not using any server or service. I've found many pointers and I might not be that informed, but having a multi language project where "the other guys" produce some "nice" javadoc contained in one directory; I'm lost to do that easily with go/go doc/godoc/... just my 2cents.
marcellanz
on 10 Sep 2019
@marcellanz I agree, there doesn't exist a user friendly way of doing this yet. This issue is open and tracking resolving that task.
As a brief update, there has been progress made on relevant components that will enable resolving this issue. So it is moving along.
dmitshur
on 10 Sep 2019
@dmitshur thanks for the update. sounds good.
marcellanz
on 10 Sep 2019
@dmitshur this would be a great feature. Is there a timeline of when this would be rolled out?
tholsapp
on 17 Oct 2019
It's not known when this issue will be complete. When there are updates, they'll be posted on this issue.
dmitshur
on 17 Oct 2019
I want to add my two cents that I am currently wrapping up my first go library after being a python developer for 5 or so years, and the lack of easy static docs has me a little lost as well. Streamlined documentation is so important for team projects, and using godoc.org isn't a viable option for many in-house projects.
My use case: We already host most of our docs on readthdocs.org in a private repo. If i had a way of generating a static html file for my projects, then I might be able to upload them to their own page and keep our docs all in one place.
bpeake-illuscio
on 21 Dec 2019
Any update on this or any external library currently able to do this. I need to host go documentation on private Gitlab. Thanks
dharmjit
on 20 Jan 2020
I wrote a small prototype that can output static html: https://github.com/netlify/godoc-static
(not in any way complete, will try to write a blog post on it soon)
mraerino
on 20 Jan 2020
@dmitshur : Is someone actively working on this? Is there a public discussion or collection of PRs that we can follow to get a better sense of the progress and perhaps where we could pitch in?
zomglings
on 1 Feb 2020
I have workaround that using the wget command for that. Example: snippet
I have a similar issue with that. I'm using GitLab for my projects and I have decide to create and share with some handy GitLab CI YAML templates for Go projects that will automatically generate a static HTML Go documentation from the godoc tool without any external packages: https://gitlab.com/tymonx/gitlab-ci
Example: Go Logger documentation
Two nice features:
- Embedded Go source code files
- Search box is referencing to GitLab
I'm also waiting for this feature :)
tymonx
on 16 May 2020
Related issues
go101
路
3Comments
natefinch
路
3Comments
ajstarks
路
3Comments
Miserlou
路
3Comments
bbodenmiller
路
3Comments
Most helpful comment
@dmitshur : Is someone actively working on this? Is there a public discussion or collection of PRs that we can follow to get a better sense of the progress and perhaps where we could pitch in?