godoc-static - Generate static documentation for your packages

[tsl...@gmail.com]

Repository: https://gitlab.com/tslocum/godoc-static

Demo output: https://docs.rocketnine.space

Inspired by the recent news of godoc.org shutting down I have created godoc-static.  While we could all migrate to pkg.go.dev, we could also host and update our documentation ourselves.

When invoked, "godoc -http=localhost:####" is started, relevant package documentation pages and source code is scraped and rewritten to fix styling, expanding content, etc., then godoc is terminated.

Note that while things seem to work, I have only focused on shipping the MVP so far.  Here be dragons.  For instance, to get this to work on my VPS I had to set  GO111MODULE to off and clone relevant package sources to GOPATH.

[Nick]

Quoth tsl...@gmail.com:

> Inspired by the recent news of godoc.org shutting down I have created
> godoc-static.  While we could all migrate to pkg.go.dev, we could also host and
> update our documentation ourselves.

Cool, sounds interesting, I like the idea of more tools to make more
distributed hosting of go stuff easier!

> When invoked, "godoc -http=localhost:####" is started, relevant package
> documentation pages and source code is scraped and rewritten to fix styling,
> expanding content, etc., then godoc is terminated.

Interesting approach. Did you consider taking the code that godoc
uses (either direct copying or including it somehow) and generating
the HTML directly? I can imagine that might not be straightforward,
but I'm interested to hear why you chose this approach instead.
Without having looked at the code, I would imagine it would be more
liable to break with future versions of godoc which change the
output.

Anyway, good job, I may use it myself soon, and will let you know
how I get on.

Nick

[tsl...@gmail.com]

Hey Nick, I did consider that and hope to still visit it.  I chose to scrape instead because the output requires only minimal alteration to achieve the desired result. Example code expansion is rewritten to not require JavaScript by using <details> and <summary> and not much more.  Large changes to output from the godoc tool can certainly break godoc-static in its current state.  Assistance with exploring generating similar output without using godoc would be appreciated.

[tsl...@gmail.com]

I've had some time to polish this project somewhat. It should be fairly usable.

I've added ZIP archive generation to allow browsing offline without godoc.

Any additional feedback is welcome.

[Trevor Slocum]

godoc-static v0.1.8 is now available featuring improved support for Go modules.

[tapi...@gmail.com]

Cool.

BTW, there is another docs generator: https://github.com/go101/gold (written by me).