jogramming / godocdown

Format package documentation (godoc) as GitHub friendly Markdown

godocdown

-- Command godocdown generates Go documentation in a GitHub-friendly Markdown format.

$ go get github.com/robertkrimen/godocdown/godocdown

$ godocdown /path/to/package > README.markdown

# Generate documentation for the package/command in the current directory
$ godocdown > README.markdown

# Generate standard Markdown
$ godocdown -plain .

This program is targeted at providing nice-looking documentation for GitHub. With this in mind, it generates GitHub Flavored Markdown (http://github.github.com/github-flavored-markdown/) by default. This can be changed with the use of the "plain" flag to generate standard Markdown.

Install

go get github.com/robertkrimen/godocdown/godocdown

Example

http://github.com/robertkrimen/godocdown/blob/master/example.markdown

Usage

-output=""
    Write output to a file instead of stdout
    Write to stdout with -

-template=""
    The template file to use

-no-template=false
    Disable template processing

-plain=false
    Emit standard Markdown, rather than Github Flavored Markdown

-heading="TitleCase1Word"
    Heading detection method: 1Word, TitleCase, Title, TitleCase1Word, ""
    For each line of the package declaration, godocdown attempts to detect if
    a heading is present via a pattern match. If a heading is detected,
    it prefixes the line with a Markdown heading indicator (typically "###").

    1Word: Only a single word on the entire line
        [A-Za-z0-9_-]+

    TitleCase: A line where each word has the first letter capitalized
        ([A-Z][A-Za-z0-9_-]\s*)+

    Title: A line without punctuation (e.g. a period at the end)
        ([A-Za-z0-9_-]\s*)+

    TitleCase1Word: The line matches either the TitleCase or 1Word pattern

Templating

In addition to Markdown rendering, godocdown provides templating via text/template (http://golang.org/pkg/text/template/) for further customization. By putting a file named ".godocdown.template" (or one from the list below) in the same directory as your package/command, godocdown will know to use the file as a template.

# text/template
.godocdown.markdown
.godocdown.md
.godocdown.template
.godocdown.tmpl

A template file can also be specified with the "-template" parameter

Along with the standard template functionality, the starting data argument has the following interface:

{{ .Emit }}
// Emit the standard documentation (what godocdown would emit without a template)

{{ .EmitHeader }}
// Emit the package name and an import line (if one is present/needed)

{{ .EmitSynopsis }}
// Emit the package declaration

{{ .EmitUsage }}
// Emit package usage, which includes a constants section, a variables section,
// a functions section, and a types section. In addition, each type may have its own constant,
// variable, and/or function/method listing.

{{ if .IsCommand  }} ... {{ end }}
// A boolean indicating whether the given package is a command or a plain package

{{ .Name }}
// The name of the package/command (string)

{{ .ImportPath }}
// The import path for the package (string)
// (This field will be the empty string if godocdown is unable to guess it)

-- godocdown http://github.com/robertkrimen/godocdown