generate godoc documentation for an entire project?

Question

I've been wrestling with godoc and found that "go doc" is more for providing usage help from the command line for instance:

go doc -cmd -u

lists the package comment and any functions (or other entities)

go doc *function*

then shows the documentation for an individual function (or other entity)

It seems there is a related tool called godoc. godoc also seems to generate html on a per package and function basis. E.g.

godoc -html hello

Generates html containing the package comment only to stdout

godoc is a really confusing name given we have go doc as well!

How can I create static documentation for the whole project?

This is similar to Godoc, create html for entire package which may have been misinterpreted as asking about documentation for packages rather than projects. I want a build step I can use in a project that may in principle contain many packages and apps.

Answer 1

I was struggling to do this and finally, the thing that worked for me is

1. make sure you have "wget" installed(I am using mac, so had to install it using x-code)

2. log in as root user and modify the file called "robots.txt" to remove the line "Disallow : /" as this prevents wget to download the site recursively. The "robots.txt" file should be in $GOROOT path.

3. open a cmd and start the godocs server using the below command

   godoc -http=:6060
   

   I have my local path configured to this port.

4. Open another cmd and run the below command.

   wget -r -np -N -E -p -k http://localhost:6060/pkg/myproject
   

   you can mention the path of the project to have the html docs downloaded for entire project.

Answer 2

is there a canonical way to generate documentation for offline use even using godoc?

Go 1.12 (February 2019) is clearer on that:

godoc and go doc

In Go 1.12, godoc no longer has a command-line interface and is only a web server.
Users should use go doc for command-line help output instead.

go doc now supports the -all flag, which will cause it to print all exported APIs and their documentation, as the godoc command line used to do.

cmd/doc: add -all flag to print all documentation for package

Unlike the one for the old godoc, you need the -u flag to see unexported symbols.
This seems like the right behavior: it's consistent.

Answer 3

This can be also achieved using simple 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 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

Answer 4

You can try Golds, which is an alternate Go docs generation tool (and a local docs server / code reader).

Under your project directory, you can run any of the following commands to generate HTML docs for your Go project:

• golds -gen -nouses -plainsrc -wdpkgs-listing=promoted ./...
• golds -gen -nouses -wdpkgs-listing=promoted ./...
• golds -gen -wdpkgs-listing=promoted ./...

The first command generates the most compact docs and the last one generates the full docs, which size is 6 times of the compact docs.

BTW, I'm the author of Golds. Hope you this tool would satisfy your need.