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

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)
• Types
  • type Function
    • func NewFunction(fset *token.FileSet, f *doc.Func) Function

Variables

Simple error to indicate empty folder

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

Functions

func Generate

func Generate(root string, pkg *Package)

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

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