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: generate static docs #2381

Open
moraes opened this Issue Oct 18, 2011 · 18 comments

Comments

Projects
None yet
10 participants
@moraes
Contributor

moraes commented Oct 18, 2011

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.
@bradfitz

This comment has been minimized.

Member

bradfitz commented Oct 21, 2011

Comment 1:

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.

@adg

This comment has been minimized.

Contributor

adg commented Oct 26, 2011

Comment 2:

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.
@moraes

This comment has been minimized.

Contributor

moraes commented Oct 31, 2011

Comment 3:

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
@rsc

This comment has been minimized.

Contributor

rsc commented Dec 9, 2011

Comment 4:

Labels changed: added priority-later.

@adg

This comment has been minimized.

Contributor

adg commented Dec 19, 2011

Comment 5:

Owner changed to ---.

Status changed to HelpWanted.

@adg

This comment has been minimized.

Contributor

adg commented Mar 18, 2013

Comment 7:

Labels changed: added godoc.

@gopherbot

This comment has been minimized.

gopherbot commented Mar 20, 2013

Comment 8 by pedromorgan:

Yes please
@josharian

This comment has been minimized.

Contributor

josharian commented Oct 11, 2013

Comment 9:

You can ask wget to ignore robots.txt by adding the flag `-e robots=off`.
@rsc

This comment has been minimized.

Contributor

rsc commented Nov 27, 2013

Comment 10:

Labels changed: added go1.3maybe.

@rsc

This comment has been minimized.

Contributor

rsc commented Dec 4, 2013

Comment 11:

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

@rsc

This comment has been minimized.

Contributor

rsc commented Dec 4, 2013

Comment 12:

Labels changed: added repo-tools.

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

@rsc rsc changed the title from cmd/godoc: generate static docs to x/tools/cmd/godoc: generate static docs Apr 14, 2015

@rsc rsc removed the repo-tools label Apr 14, 2015

@Kegsay

This comment has been minimized.

Kegsay commented Nov 2, 2016

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.

@gopherbot

This comment has been minimized.

gopherbot commented Oct 24, 2017

Change https://golang.org/cl/72890 mentions this issue: godoc/internal/render: add render package for text formatting

@dsnet

This comment has been minimized.

Member

dsnet commented Oct 24, 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 dsnet self-assigned this Oct 31, 2017

@dsnet dsnet removed the help wanted label Oct 31, 2017

@lgierth

This comment has been minimized.

lgierth commented Nov 6, 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.

@dsnet

This comment has been minimized.

Member

dsnet commented Nov 6, 2017

You can download the patch from CL/72890 and run render_docs.go directly.

@joeldeaguero

This comment has been minimized.

joeldeaguero commented Feb 19, 2018

Suggestion for those using this workaround, you may eventually want to add this to your wget command line: -X debug/pprof

@lgierth

This comment has been minimized.

lgierth commented Feb 19, 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.

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