forked from princjef/gomarkdoc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
225 lines (225 loc) · 10.6 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
// Package gomarkdoc formats documentation for one or more packages as markdown
// for usage outside of the main https://pkg.go.dev site. It supports custom
// templates for tweaking representation of documentation at fine-grained
// levels, exporting both exported and unexported symbols, and custom formatters
// for different backends.
//
// Command Line Usage
//
// If you want to use this package as a command-line tool, you can install the
// command by running:
//
// GO111MODULE=on go get -u github.com/princjef/gomarkdoc/cmd/gomarkdoc
//
// The command line tool supports configuration for all of the features of the
// importable package:
//
// $ gomarkdoc --help
// generate markdown documentation for golang code
//
// Usage:
// gomarkdoc [flags] [package ...]
//
// Flags:
// -c, --check Check the output to see if it matches the generated documentation. --output must be specified to use this.
// --config string File from which to load configuration (default: .gomarkdoc.yml)
// --footer string Additional content to inject at the end of each output file.
// --footer-file string File containing additional content to inject at the end of each output file.
// -f, --format string Format to use for writing output data. Valid options: github (default), azure-devops, plain (default "github")
// --header string Additional content to inject at the beginning of each output file.
// --header-file string File containing additional content to inject at the beginning of each output file.
// -h, --help help for gomarkdoc
// -u, --include-unexported Output documentation for unexported symbols, methods and fields in addition to exported ones.
// -o, --output string File or pattern specifying where to write documentation output. Defaults to printing to stdout.
// --repository.default-branch string Manual override for the git repository URL used in place of automatic detection.
// --repository.path string Manual override for the path from the root of the git repository used in place of automatic detection.
// --repository.url string Manual override for the git repository URL used in place of automatic detection.
// -t, --template stringToString Custom template string to use for the provided template name instead of the default template. (default [])
// --template-file stringToString Custom template file to use for the provided template name instead of the default template. (default [])
// -v, --verbose count Log additional output from the execution of the command. Can be chained for additional verbosity.
// --version Print the version.
//
// The gomarkdoc command processes each of the provided packages, generating
// documentation for the package in markdown format and writing it to console.
// For example, if you have a package in your current directory and want to
// send it to a documentation markdown file, you might do something like this:
//
// gomarkdoc --output doc.md .
//
// Package Specifiers
//
// The gomarkdoc tool supports generating documentation for both local packages
// and remote ones. To specify a local package, start the name of the package
// with a period (.) or specify an absolute path on the filesystem. All other
// package signifiers are assumed to be remote packages. You may specify both
// local and remote packages in the same command invocation as separate
// arguments.
//
// Output Redirection
//
// By default, the documentation generated by the gomarkdoc command is sent to
// standard output, where it can be redirected to a file. This can be useful if
// you want to perform additional modifications to the documentation or send it
// somewhere other than a file. However, keep in mind that there are some
// inconsistencies in how various shells/platforms handle redirected command
// output (for example, Powershell encodes in UTF-16, not UTF-8). As a result,
// the --output option described below is recommended for most use cases.
//
// gomarkdoc . > doc.md
//
// If you want to redirect output for each processed package to a file, you can
// provide the --output/-o option, which accepts a template specifying how to
// generate the path of the output file. A common usage of this option is when
// generating README documentation for a package with subpackages (which are
// supported via the ... signifier as in other parts of the golang toolchain).
// In addition, this option provides consistent behavior across platforms and
// shells:
//
// gomarkdoc --output '{{.Dir}}/README.md' ./...
//
// You can see all of the data available to the output template in the
// PackageSpec struct in the github.com/princjef/gomarkdoc/cmd/gomarkdoc
// package.
//
// Template Overrides
//
// The documentation information that is output is formatted using a series of
// text templates for the various components of the overall documentation which
// get generated. Higher level templates contain lower level templates, but
// any template may be replaced with an override template using the
// --template/-t option. The full list of templates that may be overridden are:
//
// - file: generates documentation for a file containing one or more
// packages, depending on how the tool is configured. This is the
// root template for documentation generation.
//
// - package: generates documentation for an entire package.
//
// - type: generates documentation for a single type declaration, as well
// as any related functions/methods.
//
// - func: generates documentation for a single function or method. It may
// be referenced from within a type, or directly in the package,
// depending on nesting.
//
// - value: generates documentation for a single variable or constant
// declaration block within a package.
//
// - index: generates an index of symbols within a package, similar to what
// is seen for godoc.org. The index links to types, funcs,
// variables, and constants generated by other templates, so it may
// need to be overridden as well if any of those templates are
// changed in a material way.
//
// - example: generates documentation for a single example for a package or
// one of its symbols. The example is generated alongside whichever
// symbol it represents, based on the standard naming conventions
// outlined in https://blog.golang.org/examples#TOC_4.
//
// - doc: generates the freeform documentation block for any of the above
// structures that can contain a documentation section.
//
// Overriding with the -t option uses a key-vaule pair mapping a template name
// to the file containing the contents of the override template to use.
// Specified template files must exist:
//
// gomarkdoc -t package=custom-package.gotxt -t doc=custom-doc.gotxt .
//
// Additional Options
//
// As with the godoc tool itself, only exported symbols will be shown in
// documentation. This can be expanded to include all symbols in a package by
// adding the --include-unexported/-u flag.
//
// gomarkdoc -u -o README.md .
//
// You can also run gomarkdoc in a verification mode with the --check/-c flag.
// This is particularly useful for continuous integration when you want to make
// sure that a commit correctly updated the generated documentation. This flag
// is only supported when the --output/-o flag is specified, as the file
// provided there is what the tool is checking:
//
// gomarkdoc -o README.md -c .
//
// If you're experiencing difficulty with gomarkdoc or just want to get more
// information about how it's executing underneath, you can add -v to show more
// logs. This can be chained a second time to show even more verbose logs:
//
// gomarkdoc -vv -o README.md .
//
// Some features of gomarkdoc rely on being able to detect information from the
// git repository containing the project. Since individual local git
// repositories may be configured differently from person to person, you may
// want to manually specify the information for the repository to remove any
// inconsistencies. This can be achieved with the --repository.url,
// --repository.default-branch and --repository.path options. For example, this
// repository would be configured with:
//
// gomarkdoc --repository.url "https://github.com/princjef/gomarkdoc" --repository.default-branch master --repository.path / -o README.md .
//
// Configuring via File
//
// If you want to reuse configuration options across multiple invocations, you
// can specify a file in the folder where you invoke gomarkdoc containing
// configuration information that you would otherwise provide on the command
// line. This file may be a JSON, TOML, YAML, HCL, env, or Java properties
// file, but the name is expected to start with .gomarkdoc (e.g.
// .gomarkdoc.yml).
//
// All configuration options are available with the camel-cased form of their
// long name (e.g. --include-unexported becomes includeUnexported). Template
// overrides are specified as a map, rather than a set of key-value pairs
// separated by =. Options provided on the command line override those provided
// in the configuration file if an option is present in both.
//
// Programmatic Usage
//
// While most users will find the command line utility sufficient for their
// needs, this package may also be used programmatically by installing it
// directly, rather than its command subpackage. The programmatic usage
// provides more flexibility when selecting what packages to work with and what
// components to generate documentation for.
//
// A common usage will look something like this:
//
// package main
//
// import (
// "go/build"
// "fmt"
// "os"
//
// "github.com/princjef/gomarkdoc"
// "github.com/princjef/gomarkdoc/lang"
// "github.com/princjef/gomarkdoc/logger"
// )
//
// func main() {
// // Create a renderer to output data
// out, err := gomarkdoc.NewRenderer()
// if err != nil {
// // handle error
// }
//
// wd, err := os.Getwd()
// if err != nil {
// // handle error
// }
//
// buildPkg, err := build.ImportDir(wd, build.ImportComment)
// if err != nil {
// // handle error
// }
//
// // Create a documentation package from the build representation of our
// // package.
// log := logger.New(logger.DebugLevel)
// pkg, err := lang.NewPackageFromBuild(log, buildPkg)
// if err != nil {
// // handle error
// }
//
// // Write the documentation out to console.
// fmt.Println(out.Package(pkg))
// }
package gomarkdoc