Go Doc Markdown

godoc alternative for static Markdown documentation.

Motivation

Standard pkg.go.dev is awesome but not suitable for private repos. You can use pkgsite as local alternative but it's not perfect. Both occasionally skip certain files and generate incomplete documentation.

As stated in the comment of an engineer from Amazon sometimes it's a nightmare. You have to checkout a repo, run local server and open it in a browser only to read documentation.

With gdmd you don't even have to host your documentation, you can keep it in your repo along with the code. The generator creates a README.md with a package documentation in a package folder. You can navigate through the documentation right in GitHub UI, any open directory with source code will render its documentation.

How to use

First, you have to

go install github.com/chocolacula/gdmd/cmd/gdmd@latest

Then generate documentation for a package in a directory

gdmd ./directory

Example

package main

The single package in the project, contains data representation, parsing, and generation logic.

Index

• Variables
• Functions
  • func Generate(root string, pkg *Package) error
• Types
  • type Function
    • func NewFunction(fset *token.FileSet, f *doc.Func) (Function, error)
  • type Package
    • func NewPackage(fset *token.FileSet, p *doc.Package, dir string, nested []Package, files []string) (Package, error)
    • func Parse(root, path string, recursive bool) (Package, error)
  • type Position
  • type Type
    • func NewType(fset *token.FileSet, t *doc.Type) (Type, error)
  • type Variable
    • func NewVariable(fset *token.FileSet, v *doc.Value) (Variable, error)
• Source files

Variables

ErrEmpty sentinel indicating empty folder

var ErrEmpty = errors.New("empty folder")

Functions

func Generate

func Generate(root string, pkg *Package) error

Generate creates Markdown files for the given [Package] and its nested packages.

Types

type Function

type Function struct {
  Doc       string
  Name      string
  Pos       Position
  Recv      string // "" for functions, receiver name for methods
  Signature string
}

Function represents a function or method declaration.

func NewFunction

func NewFunction(fset *token.FileSet, f *doc.Func) (Function, error)

type Package

type Package struct {
  Doc       string
  Name      string
  Dir       string
  Constants []Variable
  Variables []Variable
  Functions []Function
  Types     []Type
  Nested    []Package
  Files     []string
}

Package represents a Go package with its contents.

func NewPackage

func NewPackage(fset *token.FileSet, p *doc.Package, dir string, nested []Package, files []string) (Package, error)

func Parse

func Parse(root, path string, recursive bool) (Package, error)

Parse walks the directory tree rooted at root and parses all .go files it returns a [Package] for each directory containing .go files or empty [Package] and [ErrEmpty]

type Position

type Position struct {
  Filename string
  Line     int
}

Position is a file name and line number of a declaration.

type Type

type Type struct {
  Doc       string
  Name      string
  Pos       Position
  Src       string // piece of source code with the declaration
  Constants []Variable
  Variables []Variable
  Functions []Function
  Methods   []Function
}

Type is a struct or interface declaration.

func NewType

func NewType(fset *token.FileSet, t *doc.Type) (Type, error)

type Variable

type Variable struct {
  Doc   string // doc comment under the block or single declaration
  Names []string
  Src   string // piece of source code with the declaration
}

Variable represents constant or variable declarations within () or single one.

func NewVariable

func NewVariable(fset *token.FileSet, v *doc.Value) (Variable, error)

You can compare self-generated documentation with pkg.dev.