jotbot

README

JotBot - AI-powered code documentation

JotBot auto-generates missing documentation for your Go repositories (more languages to come). The documentation of this repository was entirely generated by JotBot, so feel free to check out the results in the source code.

Features

• Generate documentation for Go projects using OpenAI's GPT models (supports GPT-4)
• Apply generated documentation patches to the codebase
• Filter target files using glob patterns
• Limit the number of files and documentations generated
• Override or clear existing documentation
• Dry run mode to preview changes without applying them
• Commit changes directly to a Git branch

To-Do

• Proof-read generated documentation 😅
• Test with GPT-4 (need access)
• Add support for other languages
• Configurable OpenAI settings (temperature, top_p etc.)
• GitHub Action to generate documentation on push

If you have any ideas for new features or improvements, feel free to open an issue or start a discussion. Pull requests are also welcome.

Installation

To use JotBot as a library, run:

go get -u github.com/modernice/jotbot

To use JotBot as a CLI tool, run:

go install github.com/modernice/jotbot/cmd/jotbot@latest

Usage

Call jotbot from the command line to generate missing documentation for your Go files:

jotbot generate --key <OPENAI_API_KEY>

CLI options

• --key: OpenAI API key (required)
• --root: Root directory of the repository (default: ".")
• -f, --filter: Glob pattern(s) to filter files
• --commit: Commit changes to Git (default: true)
• --branch: Branch name to commit changes to (default: "jotbot-patch")
• --limit: Limit the number of documentations to generate (default: 0, no limit)
• --file-limit: Limit the number of files to generate documentations for (default: 0, no limit)
• --dry: Print the changes without applying them (default: false)
• --model: OpenAI model to use (default: "gpt-3.5-turbo")
• -o, --override: Override existing documentation (default: false)
• -c, --clear: Clear existing documentation (default: false)
• -v, --verbose: Enable verbose logging (default: false)

License

MIT

Documentation

Index

• type GenerateOption
  • func GenerateWith(opts ...generate.Option) GenerateOption
  • func PatchWith(opts ...patch.Option) GenerateOption
• type Option
  • func WithLogger(h slog.Handler) Option
• type Repository
  • func New(svc generate.Service, opts ...Option) *Repository
  • func (g *Repository) Files(ctx context.Context, repo string, opts ...generate.Option) (<-chan generate.File, <-chan error, error)
  • func (g *Repository) Generate(ctx context.Context, repo string, opts ...GenerateOption) (*patch.Patch, error)
  • func (g *Repository) Patch(ctx context.Context, repo fs.FS, files <-chan generate.File, ...) (*patch.Patch, error)

Types

type GenerateOption

type GenerateOption func(*generation)

GenerateOption is a type that represents an option for generating files. It is used as an argument to the Generate method of Repository to customize file generation. Two functions are provided to create GenerateOptions: GenerateWith and PatchWith. The former takes a variadic parameter of generate.Options, while the latter takes a variadic parameter of patch.Options.

func GenerateWith

func GenerateWith(opts ...generate.Option) GenerateOption

GenerateWith is an option for generating code with given options. It returns a GenerateOption that appends the given options to the generation.genOpts slice. The slice is later used in generating code.

func PatchWith

func PatchWith(opts ...patch.Option) GenerateOption

PatchWith returns a GenerateOption that appends patch options to the generation. These options are applied when generating a patch for a repository.

type Option

type Option func(*Repository)

Option is a type that represents an optional configuration for a Repository. It is a functional option that can modify the behavior of the Repository constructor. Option values can be passed to the constructor as variadic arguments and applied to the Repository using the Option function. The WithLogger Option sets the logger of the Repository.

func WithLogger

func WithLogger(h slog.Handler) Option

WithLogger returns an Option that sets the logger for a Repository. The logger is used to log messages during generation and patching. The logger must implement slog.Handler.

type Repository

type Repository struct {
	// contains filtered or unexported fields
}

Repository represents a Jotbot repository. It provides methods for generating and patching files in the repository. Use the New function to create a new Repository instance. The Generate method generates files in the repository using a generate.Service, while the Patch method patches files in the repository using a patch.Patch. The Files method returns a channel of generated files and any errors encountered during generation.

func New

func New(svc generate.Service, opts ...Option) *Repository

New returns a new *Repository that uses the provided generate.Service. Options can be passed to configure the Repository. Use WithLogger to provide a slog.Handler for logging.

func (*Repository) Files

func (g *Repository) Files(ctx context.Context, repo string, opts ...generate.Option) (<-chan generate.File, <-chan error, error)

Files returns a channel of generate.File(https://pkg.go.dev/github.com/modernice/jotbot/generate#File) and a channel of errors, and an error. It generates files for the repository located at the given `repo` path, using the configured generate.Service(https://pkg.go.dev/github.com/modernice/jotbot/generate#Service) and options. If an error occurs during generation, it is returned immediately. The returned channels are closed when there are no more files or errors to be sent.

func (*Repository) Generate

func (g *Repository) Generate(ctx context.Context, repo string, opts ...GenerateOption) (*patch.Patch, error)

Generate generates a patch for a repository at path repo. It accepts a context.Context and a GenerateOption variadic parameter that is used to configure the generation process. It returns the resulting *patch.Patch and an error (if any).

func (*Repository) Patch

func (g *Repository) Patch(ctx context.Context, repo fs.FS, files <-chan generate.File, opts ...patch.Option) (*patch.Patch, error)

Patch applies comments to the source code files in a file system. It takes a context.Context, an fs.FS, a <-chan generate.File and zero or more patch.Option arguments. It returns a *patch.Patch and an error.