Usage

Generating documentation

The simplest form of using doc2go is as follows:

doc2go ./...

When run inside a Go module, this will generate documentation for the current package and all its descendants into the “_site” directory.

The generated website is standalone, and can be deployed to your chosen web host as-is.

Specifying the input

doc2go expects one or more import path patterns.

./... is shorthand for the package in the current directory and its descendants. You can specify one or more import paths explicitly to generate documentation for those packages.

doc2go github.com/yuin/goldmark github.com/yuin/goldmark/ast

Add the /... suffix to an import path to generate documentation for that package and all its descendants.

doc2go go.uber.org/zap/...

Third-party packages

You can generate documentation for third-party packages with doc2go.

To do this, pass in their module paths to the command, and suffix each with /....

doc2go go.uber.org/zap/... github.com/rs/zerolog/...

All specified package must be present in your current project’s go.mod.

Standard library

doc2go can generate the API reference for the Go standard library with the following command:

doc2go std

Changing the output

Output directory

Add an -out flag if you prefer something other than “_site”.

doc2go -out public ./...

The directory will be created if it doesn’t exist.

Home page

By default, the landing page of the generated website is an index of the topmost Go packages in the generation scope.

So if you’re generating documentation for the package example.com/foo, in the generated website:

• / is a page that links to example.com/foo
• /example.com/foo holds documentation for example.com/foo
• /example.com/foo/bar holds documentation for example.com/foo/bar

doc2go supports a -home flag that allows you to change this. Given the above, if you run:

doc2go -home example.com/foo ./...

Then, in the generated website:

• / holds documentation for example.com/foo
• /bar holds documentation for example.com/foo/bar

Base name

All generated pages use the name “index.html”. For example, the documentation for encoding/json will go into _site/encoding/json/index.html.

You can change this to something else with the -basename flag.

doc2go -basename index.htm ./...

Use this to make doc2go’s output compatible with Hugo.

doc2go -basename _index.html # other flags ...

See Embedding into Hugo for more.

Internal packages

doc2go generates documentation for all packages that match the specified patterns. In this documentation, it includes a list of subpackages for a package at the bottom of the documentation for that package.

By default, internal packages are not included in the list of subpackages, but their documentation is still there. That is, given example.com/foo/internal, doc2go will generate documentation the package, but it will not list as a subpackage of example.com/foo. If a user knows it’s there, they’ll be able to visit it.

Use doc2go’s -internal flag to include internal packages in the subpackage listing.

doc2go -internal ./...

With this flag enabled, example.com/foo/internal will be listed as a subpackage of example.com/foo.

CLI Reference

USAGE: doc2go [OPTIONS] PATTERN ...

Generates API documentation for packages matching PATTERNs.
Specify ./... to match the package in the current directory
and all its descendants.

	doc2go ./...

OPTIONS

  -basename NAME
	base name of generated files. Defaults to index.html.
  -out DIR
	write files to DIR. Defaults to _site.
  -subdir NAME
	generate output to DIR/NAME instead of DIR.
	An index of siblings of NAME will be generated in DIR.
	Use for generating versioned documentation.
  -pkg-version VERSION
	include VERSION in the generated HTML.
	Applies only to the standalone website.
  -home PATH
	import path for the home page of the documentation.
	Packages that aren't descendants of this path will be omitted.
  -pagefind[=auto|true|false|PATH]
	enable or disable client-side page search.
	See -help=pagefind for more information.
	Defaults to auto.
  -embed
	generate partial HTML pages fit for embedding.
  -internal
	include internal packages in package listings.
  -frontmatter FILE
	generate front matter in HTML files via template in FILE.
	See -help=frontmatter for more information.
  -rel-link-style STYLE
	use STYLE for relative links. One of:
	  plain: render as-is (e.g. ../foo)
	  directory: render as a directory (e.g. ../foo/)
	Defaults to plain.
  -highlight [MODE:][THEME]
	use THEME to highlight code blocks.
	MODE, if any, is one of 'auto', 'inline', and 'classes'
	and specifies the method of highlighting.
	See -help=highlight for more information.
  -highlight-list-themes
	print a list of available themes.
  -highlight-print-css
	print the CSS for the THEME specified in -highlight.
  -pkg-doc PATH=TEMPLATE
	generate links for PATH and its children via TEMPLATE.
	See -help=pkg-doc for more information.
  -config RC
	read configuration from the given file. Defaults to doc2go.rc.
	See -help=config for more information.
  -tags TAG,...
	list of comma-separated build tags.
  -debug[=FILE]
	print debugging output to stderr or FILE, if specified.
  -version
	report the tool version.
  -h, -help
	prints this message.