Package template_functions

This package provides a set of functions that are passed to the template engine to generate documentation.

The functions are used to format the documentation in a way that is easy to read and understand.

You can utilize these functions in your own custom templates to generate documentation for your packages with customize formatting/behvior if the standard templates provided by godoc-readme do not meet your needs.

Functions

func Alert

func Alert(pkg *packages.Package, notes map[string][]*doc.Note) func(string) string

Alert returns a function that, given the name of a target, returns a string representing the alerts for that target Can be used in a template by calling {{ Alert "target_name" }} where target_name is the name of the package, a Type, Func, Var, or Const in the package. Alerts are rendered AFTER the doc comment for the target by default. Provide your own templates to modify this behavior.

[!NOTE] Use this alert to provide additional information

[!WARNING] Use this alert to warn users about potential issues

[!IMPORTANT] Use this alert to highlight important information

[!CAUTION] Use this alert to caution users about serious issues

[!TIP] Use this alert to provide helpful tips to users

func CodeBlock

func CodeBlock(pkg *packages.Package) func(lang ...string) string

CodeBlock returns the start (or end) of a code block in markdown If you provide a language, it will be used to specify the language format of the code block In a template, you should call this function like this: {{ code_block "go" }} or {{ code_block }} to start the code block and {{ code_block }} to end the code block after you've rendered the contens between the start and end of the code block

Example:

{{ code_block "go" }}
package main

   func main() {
       fmt.Println("Hello, World!")
   }

{{ code_block }}

This will render the following markdown:

package main

   func main() {
       fmt.Println("Hello, World!")
   }

func ExampleCode

func ExampleCode(pkg *packages.Package) func(*doc.Example) string

ExampleCode returns a function, given a package containing the example code, that returns a string representation of a doc.Example (Example Function in a package) You can call this function in a template by using {{ example . }} where . is a *doc.Example instance

func FormatNode

func FormatNode(pkg *packages.Package) func(ast.Node) string

Format returns the string representation of an ast.Node in a package Can be called in a template by using the fmt function {{ format . }} where . is a type that implements *ast.Node

func Link

func Link(pkg *packages.Package) func(string, ast.Node) string

Link returns a markdown link to the location of the ast.Node in a package Can be called in a template by using the fmt function {{ link . }} where . is a type that implements *ast.Node

func PackageDocString

func PackageDocString(doc string) string

PackageDocString returns a copy of doc with godoc notes replaced with github markdown notes Usage: {{ DocString .Doc }} where .Doc is a string containing godoc notes for a PACKAGE

func Section

func Section(doc string, n int) string

Section returns a copy of doc with n number of >'s added to the beginning of each line. You can call this function in a template by using {{ section .Doc 1 }} where .Doc is string field. Example:

Section("This is a section", 1) returns "> This is a section"