# README
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 numbersalert
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 pwdreturns ./path
Additionally, the following functions are available in the template engine:
base
: [filepath.Base] Returns the base name of a file path
ExampleReadme_Generate
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
orRenderTypes | 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:
- Replace all hard-tabs(
\t
) with 4 single space characters ()
- Remove leading whitespace from blank lines
- 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