godocgen

README

godocgen

godocgen is a CLI tool to generate godocs in markdown format in your repository.

This tool helps you in creating & maintaining documentation for your private Go codebases. The generated markdown files can be kept in the same repository, removing the need for running a separate godoc server.

Usage

$ godocgen
NAME:
   godocgen - Document & maintain your Go documentation in markdown files

USAGE:
   godocgen [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --source value, --src value  path to packages that have to be documented
   --name value                 name of markdown file to output to (default: "GODOC.md")
   --help, -h                   show help (default: false)
godocgen version

Documentation

Overview

Package godocgen parses Go packages and indexes constants, functions and types.

`godocgen` keeps your private Go repositories documented with the same source code & repository.

Index

• func GetSourcePackages(path string) ([]string, error)
• func ToMD(w io.Writer, text string)
• func WriteMDTemplate(idx *PackageIndex, outPath string) error
• func WriteMarkdown(idx *PackageIndex, outPath string) error
• type Blockable
• type Const
• type Content
  • func (c Content) ToString() string
• type Example
• type Func
• type GoCode
  • func (c GoCode) ToString() string
• type Heading1
  • func (h Heading1) ToString() string
• type Heading2
  • func (h Heading2) ToString() string
• type Heading3
  • func (h Heading3) ToString() string
• type Heading4
  • func (h Heading4) ToString() string
• type Index
  • func NewIndex(md *Markdown) Index
  • func (i Index) ToString() string
• type IndexEntry
• type Markdown
  • func NewMarkdown() *Markdown
  • func (d *Markdown) Append(b Blockable)
  • func (d *Markdown) Content() string
  • func (d *Markdown) Prepend(b ...Blockable)
• type PackageIndex
  • func GetPackageIndex(src string) (*PackageIndex, error)
• type Type
• type Var

Functions

func GetSourcePackages

func GetSourcePackages(path string) ([]string, error)

GetSourcePackages returns all package directories in path excludes vendor directories

func ToMD

func ToMD(w io.Writer, text string)

ToMD converts comment text to formatted Markdown. The comment was prepared by DocReader, so it is known not to have leading, trailing blank lines nor to have trailing spaces at the end of lines. The comment markers have already been removed.

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation is formatted as a heading.

A span of indented lines is converted into a pre block, with the common indent prefix removed.

URLs in the comment text are converted into links.

func WriteMDTemplate

func WriteMDTemplate(idx *PackageIndex, outPath string) error

WriteMDTemplate creates a markdown output using an template

func WriteMarkdown

func WriteMarkdown(idx *PackageIndex, outPath string) error

WriteMarkdown writes indexed documents as markdown content

Types

type Blockable

type Blockable interface {
	ToString() string
}

Blockable is implement by content blocks

type Const

type Const struct {
	Doc     string
	Snippet string
}

Const is a single or a block of constants in a package

type Content

type Content string

Content is plain text

func (Content) ToString

func (c Content) ToString() string

ToString returns markdown string

type Example

type Example struct {
	Name    string
	ForFunc string
	Suffix  string
	Doc     string
	Snippet string
	Output  string
}

Example demonstrates use of functions & types in a package

type Func

type Func struct {
	Name     string
	Doc      string
	Snippet  string
	Recv     string
	Examples []Example
}

Func is a package level function

type GoCode

type GoCode string

GoCode is a Go code block

func (GoCode) ToString

func (c GoCode) ToString() string

ToString returns code block wrapped in `pre` quotes

type Heading1

type Heading1 string

Heading1 is H1

func (Heading1) ToString

func (h Heading1) ToString() string

ToString returns markdown string

type Heading2

type Heading2 string

Heading2 is H2

func (Heading2) ToString

func (h Heading2) ToString() string

ToString returns markdown string

type Heading3

type Heading3 string

Heading3 is H3

func (Heading3) ToString

func (h Heading3) ToString() string

ToString returns markdown string

type Heading4

type Heading4 string

Heading4 is H4

func (Heading4) ToString

func (h Heading4) ToString() string

ToString returns markdown string

type Index

type Index []IndexEntry

Index is a list of all labels in the document

func NewIndex

func NewIndex(md *Markdown) Index

NewIndex creates a new index from all headings in the markdown doc

func (Index) ToString

func (i Index) ToString() string

ToString returns index serialized as a list

type IndexEntry

type IndexEntry struct {
	Label string
	Level int
}

IndexEntry is an entry that is rendered as a list item

type Markdown

type Markdown struct {
	Blocks []Blockable
}

Markdown is a collection of blocks

func NewMarkdown

func NewMarkdown() *Markdown

NewMarkdown creates an empty markdown object

func (*Markdown) Append

func (d *Markdown) Append(b Blockable)

Append adds a block to Markdown

func (*Markdown) Content

func (d *Markdown) Content() string

Content returns a string representation of the markdown object

func (*Markdown) Prepend

func (d *Markdown) Prepend(b ...Blockable)

Prepend prepends a block to Markdown

type PackageIndex

type PackageIndex struct {
	Name string
	Dir  string
	Doc  string

	Vars     []Var
	Consts   []Const
	Funcs    []Func
	Types    []Type
	Examples []Example
}

PackageIndex contains all parsed types & functions information

func GetPackageIndex

func GetPackageIndex(src string) (*PackageIndex, error)

GetPackageIndex parses and returns all the documentation content in a package

type Type

type Type struct {
	Name     string
	Doc      string
	Snippet  string
	Consts   []Const
	Funcs    []Func
	Methods  []Func
	Examples []Example
}

Type captures public types available at package level

type Var

type Var struct {
	Doc     string
	Snippet string
}

Var is a single or a block of variables in a package