rebecca

README

Rebecca

Rebecca is a readme generator.

Managing the GitHub readme for your Go project can be a drag. When creating jennifer I found examples copied into the markdown would get out of date, and documentation was duplicated. I created rebecca to solve this: see README.md.tpl in the jennifer repo for a real world example.

Install

go install github.com/dave/rebecca/cmd/becca@latest

Usage

becca [-package={your-package}]

Rebecca will read README.md.tpl and overwrite README.md with the rendered template. The package specified on the command line is parsed (if no package is specified, it is detected from the current working directory).

The package is scanned for examples and documentation. Rebecca uses the Go template library, and adds some custom template functions:

Example

{{ "ExampleFoo" | example }}

This prints the code and expected output for the ExampleFoo example.

Doc

{{ "Foo" | doc }}

This prints the documentation for Foo. All package level declarations are supported (func, var, const etc.)

{{ "Foo.Bar" | doc }}

This prints the documentation for the Bar member of the Foo type. Methods and struct fields are supported.

You can also specify which sentances to print, using Go slice notation:

{{ "Foo[i]" | doc }}
{{ "Foo[i:j]" | doc }}
{{ "Foo[i:]" | doc }}
{{ "Foo[:i]" | doc }}

See here and here for real-world examples of this.

Code, Output

{{ "ExampleFoo" | code }}

This prints just the code for the ExampleFoo example.

{{ "ExampleFoo" | output }}

This prints just the expected output for the ExampleFoo example.

Documentation

Overview

Package rebecca is a readme generator.

Index

• type CodeMap
  • func NewCodeMap(pkg string, dir string) (*CodeMap, error)
  • func (m *CodeMap) DocFunc(in string) string
  • func (m *CodeMap) ExampleFunc(plain bool) func(in string) string
  • func (m *CodeMap) OutputFunc(in string) string

Types

type CodeMap

type CodeMap struct {
	Name string

	Examples map[string]*doc.Example
	Comments map[string]string
	// contains filtered or unexported fields
}

func NewCodeMap

func NewCodeMap(pkg string, dir string) (*CodeMap, error)

func (*CodeMap) DocFunc

func (m *CodeMap) DocFunc(in string) string

func (*CodeMap) ExampleFunc

func (m *CodeMap) ExampleFunc(plain bool) func(in string) string

func (*CodeMap) OutputFunc

func (m *CodeMap) OutputFunc(in string) string