README
¶
GoPages 
Generate a documentation site from your Go files, then upload the static files to your site.
Includes GitHub Pages integration to easily update your docs in one command.
For installation and usage, read this project's very own gopages site: https://johnstarich.com/go/gopages
Documentation
¶
Overview ¶
Command gopages generates static files for Go documentation, formatted with godoc.
Installation ¶
To install gopages, run the following command:
go install github.com/johnstarich/go/gopages@latest
Getting started ¶
Generate documentation for your module by running gopages without any flags.
A 'go.mod' file must be present in the current directory.
cd ./mymodule gopages
NOTE: Install gopages with Go v1.19 or higher to generate documentation with improved formatting.
Usage of gopages:
-base string
Base URL to use for static assets
-brand-description string
Branding description in the top left of documentation
-brand-title string
Branding title in the top left of documentation
-gh-pages
Automatically commit the output path to the gh-pages branch. The current branch
must be clean.
-gh-pages-token string
The Git token to push with. Usually this is an API key.
-gh-pages-user string
The Git username to push with
-include-head value
Includes the given HTML file's contents in every page's '<head></head>'. Useful
for including custom analytics scripts. Must be valid HTML.
-internal
Includes 'internal' packages in the package index and unexported functions.
Useful for sharing documentation within the same development team. Note: This
only affects page generation for non-internal packages, like package lists.
Internal package docs are always generated.
-out string
Output path for static files (default "dist")
-source-link string
Custom source code link template. Disables built-in source code pages. For
example, "https://github.com/johnstarich/go/blob/master/gopages/{{.Path}}{{if .Line}}#L{{.Line}}{{end}}"
generates links compatible with GitHub and GitLab. Must be a valid Go template
and must generate valid URLs.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd provides an Exiter and a test exiter, great for testing command main() functions.
|
Package cmd provides an Exiter and a test exiter, great for testing command main() functions. |
|
gendoc
Command gendoc generates the root package's documentation.
|
Command gendoc generates the root package's documentation. |
|
watch
Command watch generates docs and starts an HTTP endpoint to serve them.
|
Command watch generates docs and starts an HTTP endpoint to serve them. |
|
internal
|
|
|
flags
Package flags parses args and returns them as a struct.
|
Package flags parses args and returns them as a struct. |
|
generate
Package generate generates documentation pages for a given package.
|
Package generate generates documentation pages for a given package. |
|
generate/source
Package source defines interfaces for generating URL links in documentation.
|
Package source defines interfaces for generating URL links in documentation. |
|
module
Package module finds a module's package path for a given file path.
|
Package module finds a module's package path for a given file path. |
|
safememfs
Package safememfs wraps go-billy/memfs's Open to correctly handle opening directories
|
Package safememfs wraps go-billy/memfs's Open to correctly handle opening directories |
Click to show internal directories.
Click to hide internal directories.