Package godoc_readme

Implements the godocs parsing and README generation from template files.

Types

type PackageReadme

type PackageReadme struct {
   Options ReadmeOptions
   Pkg     *packages.Package
   Doc     *doc.Package
   bytes.Buffer
   rel_file_path string
   file_name     string
   file          *os.File
   cwd           string
   rejected      bool
}

PackageReadme is a struct that holds the package, ast and docs of the package It's used to pass data to the readme template

type Readme

type Readme struct {
   Pkgs                       map[string]*packages.Package
   TestPkgs                   map[string]*packages.Package
   pkgs                       []*packages.Package
   options                    *ReadmeOptions
   readmes                    []*PackageReadme
   confirmation_listener      net.Listener
   confirmation_listener_port int
   confirmation_server        *http.Server
}

Readme is a struct that holds the packages, ast and docs of the package And is used to pass data to the readme template

classDiagram
   class Readme
   Readme : +map[string]*packages.Package Pkgs
   Readme : -[]*packages.Package pkgs
   Readme : -ReadmeOptions options
   Readme : +Generate() error
   Readme --> ReadmeOptions
   Readme --> PackageReadme
   class ReadmeOptions
   ReadmeOptions : -string Dir
   ReadmeOptions : -string DirPattern
   ReadmeOptions : -string TemplateFile
   class PackageReadme
   PackageReadme : +ReadmeOptions Options
   PackageReadme : +packages.Package Pkg
   PackageReadme : +doc.Package Doc

[!NOTE] Because of the simpicity of godoc-readme's templating engine, you can add powerful customizations to your documentation like the class diagram that was created using a code block and the mermaid.js library that is supported out of the box with Github markdown. (not all features are supported though.)

Methods

method Generate

func (readme *Readme) Generate() (err error)

Generate creates the README.md file for the packages that are registered with a Readme

The README is generated in the directory of the package using the template file provided or the default template in none is provided. The following template functions available in the template engine are defined in the template_functions package:

Function	Description	Example	Output
example	Renders a markdown representation of a [doc.Example] instance	{{ example . }} where . is a [doc.Example]	renders an example like
code	Renders the start (or end) of a code block in markdown, optionally specifying the language format of the code block	{{ code "go" }}fmt.Println("Hello World"){{ code }}	```go\nfmt.Println("Hello World")\n```\n
fmt	Renders a formatted string representation of an [ast.Node]	{{ fmt . }}	N/A
link	Renders a markdown link to the location of the [ast.Node] in a package	{{ link "title" . }}	[title](...) where ... is the relative link to the file ,including line numbers
alert	Renders a markdown alert message based on the notes provided in the [doc.Package]	{{ alert . "title" }}	renders the alerts with the "title" target
section	Renders an indented markdown section header	{{ section "line 1 text\nline 2 text" 1}}	>line 1 text\n>line 2 text
doc	Renders a package's doc string, including in-line alerts, package ref's, etc	{{ doc . }}	N/A
relative_path	Replaces the pwd the .	{{ relative_path "/abs/path" }} where /abs is the pwd	returns ./path

Additionally, the following functions are available in the template engine:

• base: [filepath.Base] Returns the base name of a file path

func ExampleReadme_Generate{
    readme, err := NewReadme(func(ro *ReadmeOptions) {
        ro.Dir = "../examples/mermaid"
    })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    if err = readme.Generate(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

}
 // Output:
 // 

type ReadmeOptions

type ReadmeOptions struct {
   PackageDir        string
   Dir               string
   Format            func([]byte) []byte
   package_load_mode packages.LoadMode
   Env               []string `env:"-"`
   ConfirmUpdates    bool
   Flags             template_functions.Flags
}

ReadmeOptions is a struct that holds the options for the Readme struct You can set the options via the options functions or by setting the environment variables defined in the env struct tag for the Option field

type RenderFlag

type RenderFlag uint32

RenderFlags can be used to turn on and off rendering of different sections in the README.md file.

The bitmask values are as follows:

1	2	3	4	5	6	7	...	32
Types	Funcs	TypeMethods	Vars	Consts	Examples	Alerts	TBD	RenderAll (default)

For example, to render only the types and functions in the README.md file, you would set the 1st and 2nd bits, i.e 0000 0011 or RenderTypes | RenderFuncs

Methods

method IsSet

func (f RenderFlag) IsSet(flag RenderFlag) bool

IsSet returns true if the flag is set in the RenderFlags

Functions

func FormatMarkdown

func FormatMarkdown(md []byte) []byte

FormatMarkdown applies the following formatting to the markdown:

1. Replace all hard-tabs(\t) with 4 single space characters ( )
2. Remove leading whitespace from blank lines
3. Replace multiple \n(3+) with a single \n

Vars

// The readme templates are embedded in the binary so that it can be used as a default template
// This value can be overridden by providing a template file using the --template flag or the GODOC_README_TEMPLATE_FILE environment variable
//
//go:embed templates/*
var readme_templates embed.FS