godoc-readme-gen

Overview ¶

Automatically generate a Markdown README for your Go project.

This tool creates a GitHub-flavored README.md using the same format as godoc. It includes the package summary and generates badges for pkg.go.dev and Travis CI.

This is a fork of James Frasche's project, found at https://github.com/jimmyfrasche/autoreadme.

What It Does ¶

By default, `godoc-readme-gen` will read the Go package in the working directory, and generate a `README.md` file. If the README already exists, it will not be overwritten without the `-f` flag. You can specify the path to the package directory as the final argument to the tool.

A template for the README is specified by the `-template` flag, and by default it looks for a file named `.README.template.md` in the package directory. If the default template is not found, or an alternate is not provided, the default template is used.

To view the default template, pass the `-print-template` function to dump it to stdout. You might redirect this output to a file so you may use it as the basis for creating your own custom template.

Lists and Bullets ¶

Paragraphs that start with the text "1. ", "2. ", etc. are automatically turned into lists by Markdown. Paragraphs between list items are automatically indented so that they appear as part of the same list item. Similarly for bullets, that are paragraphs that start with the text "* ".

We assume the list and/or bullets continue until the end of the text section (that is, until the next heading or end of document). But sometimes you may wish to "terminate" a list/bullet before then: to do this, insert a pseudo heading "..." before the next paragraph. The ellipses will not be inserted into the README file.

The following example illustrates this concept:

// Example List
//
// 1. Apple
//
// An Apple a day keeps the doctor away.
//
// 2. Pear
//
// Not to be confused with "pair".
//
// ...
//
// This trailing paragraph is not indented, as it is not considered to be
// part of the above list.

Automating README Generation ¶

To track changes in your godoc, and ensure that your README is always kept up to date, we recommend adding a `//go:generate` line to your Go package so that you can easily re-generate the README via the `go generate` command-line tool.

If you have one or more sub-packages in your project, you can add similar `//go:generate` lines to each, and then regenerate all of the READMEs by running `go generate ./...` from the top-level directory.

We recommend placing your high-level godoc comments in a separate project file `ϟdocϟ.go` and a `//go:generate` line beneath the `package` declaration as follows:

// Package demo shows how you might structure a "ϟdocϟ.go" file.
package demo // import "corp.example.com/demo"

//go:generate godoc-readme-gen -f -title "Demo Usage of godoc-read-me-gen"
//  To install: `go install go.jpap.org/godoc-readme-gen`

Naming this file with the given Unicode "ϟ" character ensures `go generate` generates your README **last**, because it processes files in sorted order. This is important because `godoc-readme-gen` requires your Go project to build without error (so it can parse the source code). If other generators have not yet run, or require regeneration (e.g. out-of-date `stringer` files), your source code might not "compile" and `godoc-readme-gen` will fail, stopping `go generate` from running the other generators.

Unfortunately Go source filenames are restricted to being ASCII or Unicode letters, and limited to ASCII punctuation when using modules. The allowed punctuation characters "compare before" all of the ASCII letters, so we are then forced to use a Unicode letter that always "compares after" all of the ASCII letters. We choose the ancient Greek letter koppa "ϟ" for this purpose, because it "compares after" all Greek characters too!

Examples ¶

Create a README.md for the package in directory a/b/c, with `.Title` template variable set to "A Great Package":

godoc-readme-gen -title "A Great Package" a/b/c

Overwrite the README.md in the current directory:

godoc-readme-gen -f

Copy the built-in template to a file for the creation of a new template:

godoc-readme-gen -print-template > .README.template.md

Generate using a custom template:

godoc-readme-gen -template path/to/my/readme.template.md

Template Variables ¶

The following variables are available in custom templates:

`.Name` Package name.

`.Title` The -title flag value, or package name if not provided.

`.Doc` Package-level documentation.

`.Synopsis` The first sentence from the .Doc variable.

`.ImportPath` Package import path.

`.RepoPath` The import path without the first path component. For example, the import github.com/golang/go is represented as "golang/go". This is typically the path within the repo of the package.

`.Bugs` A []string of all bugs as per godoc.

`.Commands` A []string of import paths of all main packages. In addition to the directory provided to the tool, we also check cmd/* directories for additional main packages.

`.Library` True if the package is not a main package.

`.Today` The current date in YYYY.MM.DD format.

`.Travis` True if there is a `.travis.yml` file in the package directory.

`.Examples` a map of Example with all examples from `*_test.go` files. These can be used to include selective examples into the README. The Example struct has the following fields:

.Name    Name of the example
.Code    Rendered example code similar to godoc
.Output  Example output, if any