Documentation
¶
Index ¶
- Variables
- func GenerateDocument(dir string, tpl string, out io.Writer) error
- func ParseRegoWithAnnotations(directory string) (ast.FlatAnnotationsRefSet, error)
- func RenderDocument(out io.Writer, d Document, opts ...RenderDocumentOption) error
- type Document
- type RenderDocumentOption
- type Section
- type TemplateConfig
- type TemplateKind
Constants ¶
This section is empty.
Variables ¶
var (
ErrNoAnnotations = errors.New("no annotations found")
)
Functions ¶
func GenerateDocument ¶
GenerateDocument generate a documentation file for a given module A single page is generated for the module located in the indicated directory this includes all package, subpackages and rules of the provided path.
func ParseRegoWithAnnotations ¶
func ParseRegoWithAnnotations(directory string) (ast.FlatAnnotationsRefSet, error)
ParseRegoWithAnnotations parse the rego in the indicated directory
func RenderDocument ¶
func RenderDocument(out io.Writer, d Document, opts ...RenderDocumentOption) error
RenderDocument takes a slice of Section and generate the markdown documentation either using the default embedded template or the user provided template
Types ¶
type Document ¶
type Document []Section
Document represent a page of the documentation
func ConvertAnnotationsToSections ¶
func ConvertAnnotationsToSections(as ast.FlatAnnotationsRefSet) (Document, error)
ConvertAnnotationsToSections generates a more convenient struct that can be used to generate the doc First concern is to build a coherent title structure; the ideal case is that each package and each rule has a doc, but this is not guaranteed. I couldn't find a way to call `strings.Repeat` inside go-template; thus, the title symbol is directly provided as markdown (#, ##, ###, etc.) Second, the attribute RegoPackageName of ast.Annotations are not easy to use on go-template; thus, we extract it as a string
type RenderDocumentOption ¶
type RenderDocumentOption func(*TemplateConfig)
func ExternalTemplate ¶
func ExternalTemplate(tpl string) RenderDocumentOption
ExternalTemplate is a functional option to override the documentation template When overriding the template, we assume it is located on the host file system
type Section ¶
type Section struct {
// RegoPackageName is the string representation of ast.Annotations.Path
RegoPackageName string
// Depth represent title depth for this section (h1, h2, h3, etc.). This values is derived from len(ast.Annotations.RegoPackageName)
// and smoothed such that subsequent section only defer by +/- 1
Depth int
// MarkdownHeading represent the markdown title symbol #, ##, ###, etc. (produced by strings.Repeat("#", depth))
MarkdownHeading string
// Annotations is the raw metada provided by OPA compiler
Annotations *ast.Annotations
}
Section is a sequential piece of documentation comprised of ast.Annotations and some pre-processed fields This struct exist because some fields of ast.Annotations are not easy to manipulate in go-template
type TemplateConfig ¶
type TemplateConfig struct {
// contains filtered or unexported fields
}
TemplateConfig represent the location of the template file(s)
func NewTemplateConfig ¶
func NewTemplateConfig() *TemplateConfig
type TemplateKind ¶
type TemplateKind int
TemplateKind helps us to select where to find the template. It can either be embedded or on the host filesystem
const ( TemplateKindInternal TemplateKind = iota TemplateKindExternal )
Source Files