https://github.com/dave/rebecca

Rebecca is a readme generator for Go
https://github.com/dave/rebecca

go golang readme template

Last synced: 25 days ago
JSON representation

Rebecca is a readme generator for Go

• Host: GitHub
• URL: https://github.com/dave/rebecca
• Owner: dave
• License: mit
• Created: 2017-02-19T20:17:08.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2022-05-22T16:19:56.000Z (over 2 years ago)
• Last Synced: 2024-11-09T20:04:50.213Z (about 1 month ago)
• Topics: go, golang, readme, template
• Language: Go
• Size: 15.6 KB
• Stars: 113
• Watchers: 6
• Forks: 8
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-golang-repositories - rebecca

README

        
# Rebecca

Rebecca is a readme generator. 

Managing the GitHub readme for your Go project can be a drag. When creating 

[jennifer](https://github.com/dave/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](https://github.com/dave/jennifer/blob/master/README.md.tpl) 

in the [jennifer](https://github.com/dave/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](https://github.com/dave/jennifer/blob/5f1e5084f7fff920e11d5b9098e5ae8089136a1a/README.md.tpl#L51-L58) and [here](https://github.com/dave/jennifer/blob/5f1e5084f7fff920e11d5b9098e5ae8089136a1a/README.md.tpl#L286-L299) 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.