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