28

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.

Bruce Adams
  • 4,953
  • 4
  • 48
  • 111
  • The official Go installer installs `godoc` by default. Command line use of `godoc` to print documentation will be phased out in the next release of Go. At the same time, the `go doc` command will gain the ability to print the doc for an entire package. – Charlie Tumahai Nov 02 '18 at 19:43
  • First: Always install the official Go releases and not some old debian packages. `go doc` is a command line tool and integrates well into editors or IDEs while `godoc -http :6060` lets you browse the whole documentation of all your Go packages. – Volker Nov 02 '18 at 22:35
  • The Debian package does not (or at least not obviously) include godoc. I see https://github.com/golang/go/issues/25595 will add support for this to "go doc --all" for 1.12. I'm not sure what to do for godoc for now though – Bruce Adams Nov 03 '18 at 00:11
  • if you can consider to use an alternative, try `gvm` –  Nov 03 '18 at 07:12
  • If a package depends on a particular minimum Go version, older Go installations cannot produce documentation for that package. Go needs accurate and complete type information to do that, and older versions simply don't know about new additions to the standard library; let alone new language features (i.e syntax). – Peter Nov 03 '18 at 07:55
  • All very well but is there a canonical way to generate documentation for offline use even using godoc? – Bruce Adams Nov 06 '18 at 09:07
  • The comments above are now redundant. They refer to an earlier version of the question where I was using go 1.7.4 supplied by Debian 9 which does not provide the 'godoc' and has been considered obsolete by the go community for some time. If you are passing by and have sufficient rep - consider deleting some of them. – Bruce Adams Dec 01 '18 at 23:37

4 Answers4

16

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.

VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • 1
    -all does a _package_ not the entire _project_ – Bruce Adams Jan 14 '19 at 08:04
  • 2
    @BruceAdams True (as stated in this answer). I'll have to test a `go doc -all ./...` triggers the doc for *all* packages (https://stackoverflow.com/q/28031603/6309) – VonC Jan 14 '19 at 08:07
  • 1
    Today that produces "too many periods in symbol specification" – VivaLaPanda Jan 09 '23 at 23:08
  • @VivaLaPanda Which command produces that error message? On which OS? With which version of Go? I just tested `go doc -all` and it seems to be working just fine. – VonC Jan 10 '23 at 06:54
  • @VonC `go doc -all ./...` produces the `too many periods` error mentioned by @VivaLaPanda. I'm on MacOS 13.1, running Go 1.19.3 (ARM64) – Tijmen Jan 11 '23 at 16:56
  • @Tijmen OK, what is the proper syntax for `go doc` to operate on current and all sub-packages? – VonC Jan 11 '23 at 18:07
  • @VonC I don't know; I came here trying to learn that, but ended up going with the curl approach – Tijmen Jan 12 '23 at 19:36
  • @Tijmen OK. What is the `curl` approach in this case? – VonC Jan 12 '23 at 19:43
  • @VonC, ah, my mistake, I meant to say the `wget` approach. As outlined in braj's answer below, and Roberto's comment on that answer. – Tijmen Jan 12 '23 at 21:51
5

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.

Mark Amery
  • 143,130
  • 81
  • 406
  • 459
braj
  • 2,545
  • 2
  • 29
  • 40
  • 2
    You can ask wget to ignore robots with `-e robots=off` – Roberto Jun 28 '19 at 03:12
  • @braj I know I'm a little late to the party, but have you heard of `homebrew`? It's basically `dpkg` or `apt` for macOS. Almost every part of my macOS devops toolchain was installed using the `brew` command. Check it out: https://www.digitalocean.com/community/tutorials/how-to-install-and-use-homebrew-on-macos – Moebius-Rex May 05 '21 at 22:01
  • How is homebrew relevant here? Having to run a web-server and download the documentation is backwards. Rather you should be able to generate static documentation and serve it as you will. Contrast with doxygen. Switching to root is an even bigger no no. The convenience of a web-server is great but it should be opt-in. – Bruce Adams May 03 '23 at 15:50
3

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.

T.L
  • 105
  • 8
0

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
tymonx
  • 71
  • 1
  • 5