robertkrimen / godocdown Goto Github PK

Format package documentation (godoc) as GitHub friendly Markdown

Go 99.49% Perl 0.51%

godocdown's Introduction

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

godocdown's People

Contributors

Stargazers

Watchers

godocdown's Issues

Bullet points

If my comment contains bullet points the markdown generated is strange:

// - first bullet
// - second bullet

generates:

- first bullet - second bullet

while

// - first bullet
//
// - second bullet

generates:

- first bullet 

- second bullet

Which license?

Could you tell me the license of this library?
I'm considering using this library for goose via retry-go.

Skip files starting with `_` (underscore)

Go compiler skips files starting with an underscore so they do not end up in the actual package. It would be good if godocdown followed suit.

Receive template from stdin

I want to pass dynamic template generated by bash script. I don't want to generate unnecessary temporary template just to delete later. It would be great if godocdown support reading input from stdin so I can pass my dynamic template through pipe.

Translate <, >

Add index section

Is there a way to add an index section, golang.org-style including a list of files in the package?

Hints:

Github markdown supports linking to headers. Adding a link like [Install](#install) should point to the heading anchor on the current markdown document.
Github also supports relative linking within the repo from markdown documents. E.g. adding a link like [see the example](example/example.go) to this repo would link to the example file.

Heading detection should not be applied to the output of paragraph reflowing

If reflowing a paragraph results in a final line containing only one word, then that word is incorrectly turned into a level 3 heading.
E.g. the following comment paragraph:

  // Package foo provides an example of how text width handling in gomarkdown 
  // can cause the last word of a paragraph to be placed on a line by itself.
  // It looks like processing may cause that word to have heading formatting
  // applied incorrectly

results in the following markdown:

Package foo provides an example of how text width handling in gomarkdown can
cause the last word of a paragraph to be placed on a line by itself. It looks
like processing may cause that word to have heading formatting applied
### incorrectly

feture: set title of any function

i think we can comment a line like:

go exmaples:

//@name Test Func Name
func Test(){}

render examples:

#### Test Func Name
func Test(){}

support its ?

Wrap inline code with ```go

Would be nice if the tool wrapped code snippets that appear in header comments with code blocks so that go formatting is applied, so for example

// Foo is an awesome function
//     fmt.Printf("Foo: %v\n", foo())
// produces
//     Foo: 42
// Note that this never changes.
func foo() int { 
    return 42
}

Would get generated as:

Foo is an awesome function

     fmt.Printf("Foo: %v\n", foo())

produces

    Foo: 42

Note that this never changes.

func foo() int { 
    return 42
}

Installation failed

On Ubuntu 12.10 with Go installed via (http://ppa.launchpad.net/gophers/go/ubuntu)

The installation failed:

sudo go get github.com/robertkrimen/godocdown/godocdown
/usr/lib/go/src/pkg/github.com/robertkrimen/godocdown/godocdown/dbg.go:8: undefined: dbg.Dbg

issue: relative import path being used

Manual pull-request: "out-file" flag

Hi, this tool is awesome but I had a minor need --- specifying a target output file name via args-flags. In my local copy I added this to global flag vars:

flag_outfile    = flag.String("outfile", "", "To print to a file instead of standard-output, specify a file name.")

Then in func main() at the very end changed the single fmt.Printfln(documentation) to this:

if len(*flag_outfile) > 0 {
    if err = ioutil.WriteFile(*flag_outfile, []byte(documentation), os.ModePerm); err != nil {
        panic(err)
    }
} else {
    fmt.Println(documentation)
}

Would you consider adding this (or something of this sort) to the tool source? Mainly so if you later on push other updates, I can update godocdown without having to re-apply this very minor but highly useful little customization.. ;)

Is there a way to generate docs for whole project?

Something like godocdown ./...?

Strip tabs in "package doc-comment"

I usually have all doc-comments formatted as slash-slash-tab-comment:

//  Doc goes here, after slash-slash-tab
//  
//  Another doc-comment line
package somepkg

This very first tab per line should not make it into the resulting mark-down output, so as to avoid "code formatting" for such comments. godocdown does strip this properly for funcs, types, methods, but not for the package clause, it seems?

Or maybe this is a go/doc issue, not sure..

Cannot parse constraint generic

type Foo interface{
  ~int64 | ~uint64
}

output:
illegal character U+007E '~' (and 4 more errors)

same thing happened for direct constraint usage:

func A[T int64|uint64](a T) T {

}