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

Open
moraes opened this issue Oct 18, 2011 · 28 comments
Open

x/tools/cmd/godoc: generate static docs #2381

moraes opened this issue Oct 18, 2011 · 28 comments
Assignees
Milestone

Comments

@moraes
Copy link
Contributor

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

Copy link
Contributor

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

Copy link
Contributor

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

Copy link
Contributor Author

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

Copy link
Contributor

@rsc rsc commented Dec 9, 2011

Comment 4:

Labels changed: added priority-later.

@adg

This comment has been minimized.

Copy link
Contributor

@adg adg commented Dec 19, 2011

Comment 5:

Owner changed to ---.

Status changed to HelpWanted.

@adg

This comment has been minimized.

Copy link
Contributor

@adg adg commented Mar 18, 2013

Comment 7:

Labels changed: added godoc.

@gopherbot

This comment has been minimized.

Copy link

@gopherbot gopherbot commented Mar 20, 2013

Comment 8 by pedromorgan:

Yes please
@josharian

This comment has been minimized.

Copy link
Contributor

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

Copy link
Contributor

@rsc rsc commented Nov 27, 2013

Comment 10:

Labels changed: added go1.3maybe.

@rsc

This comment has been minimized.

Copy link
Contributor

@rsc rsc commented Dec 4, 2013

Comment 11:

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

@rsc

This comment has been minimized.

Copy link
Contributor

@rsc 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 cmd/godoc: generate static docs 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.

Copy link

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

Copy link

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

Copy link
Member

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

Copy link

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

Copy link
Member

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

Copy link

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

Copy link

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

@Linuturk

This comment has been minimized.

Copy link

@Linuturk Linuturk commented Feb 26, 2019

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.

@marcellanz

This comment has been minimized.

Copy link

@marcellanz marcellanz commented Sep 10, 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.

@dmitshur

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Sep 10, 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.

@marcellanz

This comment has been minimized.

Copy link

@marcellanz marcellanz commented Sep 10, 2019

@dmitshur thanks for the update. sounds good.

@tholsapp

This comment has been minimized.

Copy link

@tholsapp tholsapp commented Oct 17, 2019

@dmitshur this would be a great feature. Is there a timeline of when this would be rolled out?

@dmitshur

This comment has been minimized.

Copy link
Member

@dmitshur dmitshur commented Oct 17, 2019

It's not known when this issue will be complete. When there are updates, they'll be posted on this issue.

@bpeake-illuscio

This comment has been minimized.

Copy link

@bpeake-illuscio bpeake-illuscio commented Dec 21, 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.

@dharmjit

This comment has been minimized.

Copy link

@dharmjit dharmjit commented Jan 20, 2020

Any update on this or any external library currently able to do this. I need to host go documentation on private Gitlab. Thanks

@mraerino

This comment has been minimized.

Copy link

@mraerino mraerino commented Jan 20, 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)

@nkashy1

This comment has been minimized.

Copy link

@nkashy1 nkashy1 commented Feb 1, 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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can’t perform that action at this time.