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