Need help with godocdown?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

robertkrimen
446 Stars 49 Forks 77 Commits 12 Opened issues

Description

Format package documentation (godoc) as GitHub friendly Markdown

Services available

!
?

Need anything else?

Contributors list

# 2,815
Perl
Go
Shell
lantern
77 commits

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.