asciidoc

package
v0.9.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 13, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type IndexConfig 

type IndexConfig struct {
	// Title is the title of the index document, if omitted it uses the module name (if present)
	Title string `json:"title,omitempty"`
	// Version is the version stamped as version attribute, if omitted it uses module version (if any)
	Version string `json:"version,omitempty"`
	// AuthorName is the full name of the author e.g. Mario Toffia (if none is set, default to current user)
	AuthorName string `json:"author,omitempty"`
	// AuthorEmail is the email of the author e.g. mario.toffia@bullen.se
	AuthorEmail string `json:"email,omitempty"`
	// Highlighter is the source highlighter to use - default is 'highlightjs'
	Highlighter string `json:"highlight,omitempty"`
	// TocTitle is the title of the generated table of contents (if set a toc is generated)
	// Default is 'Table of Contents', hence by default a TOC is generated.
	TocTitle string `json:"toc,omitempty"`
	// TocLevels determines how many levels shall it include, default 3
	TocLevels int `json:"toclevel,omitempty"`
	// A fully qualified or relative output path to where to search for images
	ImageDir string `json:"images,omitempty"`
	// HomePage is the url to homepage
	HomePage string `json:"web,omitempty"`
	// DocType determines the document type, default is book
	DocType string `json:"doctype,omitempty"`
}

IndexConfig is configuration to use when generating index template

type Producer 

type Producer struct {
	// contains filtered or unexported fields
}

Producer parses go code and produces asciidoc documentation.

func NewProducer 

func NewProducer() *Producer

NewProducer creates a new instance of a producer.

func (*Producer) CreateTemplateWithOverrides 

func (p *Producer) CreateTemplateWithOverrides() *Template

CreateTemplateWithOverrides creates a new instance of _Template_ and add the possible _Provider.overrides_ into it.

func (*Producer) EnableMacro 

func (p *Producer) EnableMacro() *Producer

EnableMacro will enable the substitution of _goasciidoc_ custom macros.

A _goasciidoc_ macro is on the following form _${gad:macro-name[:...]}_ footnote:[goad stands for goasciidoc].

func (*Producer) Generate 

func (p *Producer) Generate()

Generate will execute the generation of the documentation

func (*Producer) Include 

func (p *Producer) Include(path ...string) *Producer

Include adds one or more directory or files in any combination. The producer will sort out which are directories and which are filepaths.

If filepath, it will not do any type of checking and will blindly think it is a valid go file.

func (*Producer) IncludeInternal 

func (p *Producer) IncludeInternal() *Producer

IncludeInternal will include internal folder source files.

func (*Producer) IncludeTest 

func (p *Producer) IncludeTest() *Producer

IncludeTest will create documentation for test files as well.

func (*Producer) IncludeUnderScoreDirectories 

func (p *Producer) IncludeUnderScoreDirectories() *Producer

IncludeUnderScoreDirectories will include files that resides below directories starting with underscore.

func (*Producer) IndexConfig 

func (p *Producer) IndexConfig(overrides string) *Producer

IndexConfig will configures using SON properties and hence it will override the default IndexConfig configuration. If no override, just pass an empty string.

func (*Producer) Module 

func (p *Producer) Module(path string) *Producer

Module directs the producer to pick up module from path.

path may be a directory or a full path to go.mod. If "" it will use current directory.

func (*Producer) NoIndex 

func (p *Producer) NoIndex() *Producer

NoIndex specifies that the generated asciidoctor document will not have a index header. This is good for inclusion where a header is already present.

func (*Producer) NoToc 

func (p *Producer) NoToc() *Producer

NoToc disables the table of contents if index is enabled. Default is when index is enabled a table of contents is produced.

func (*Producer) NonExported 

func (p *Producer) NonExported() *Producer

NonExported will set renderer to render all Symbols both exported and non exported. By default only exported symbols are rendered.

func (*Producer) Outfile 

func (p *Producer) Outfile(path string) *Producer

Outfile sets a file to write to

func (*Producer) Override 

func (p *Producer) Override(name, template string) *Producer

Override will use another template instead of a built-in default for the particular name (see TemplateType for valid template names)

func (*Producer) OverrideFilePath 

func (p *Producer) OverrideFilePath(name, path string) *Producer

OverrideFilePath will use another template instead of a built-in default for the particular name (see TemplateType for valid template names) This is loaded from the in param path.

func (*Producer) PackageDoc 

func (p *Producer) PackageDoc(filepath ...string) *Producer

PackageDoc adds a relative, each package, filepath to search for overview package asciidoc.

For example _design/package.adoc will make goasciidoc to search relative each package path for this particular folder and file.

func (*Producer) StdOut 

func (p *Producer) StdOut() *Producer

StdOut writes to stdout instead onto filesystem.

func (*Producer) Writer 

func (p *Producer) Writer(w io.Writer) *Producer

Writer sets a custom writer where *everything* gets written to.

type Template 

type Template struct {
	// Templates to use when rendering documentation
	Templates map[string]*TemplateAndText
}

Template is handling all templates and actions to perform.

func NewTemplateWithOverrides 

func NewTemplateWithOverrides(overrides map[string]string) *Template

NewTemplateWithOverrides creates a new template with the ability to easily override defaults.

func (*Template) NewContext 

func (t *Template) NewContext(f *goparser.GoFile) *TemplateContext

NewContext creates a new context to be used for rendering.

func (*Template) NewContextWithConfig 

func (t *Template) NewContextWithConfig(
	f *goparser.GoFile,
	p *goparser.GoPackage,
	config *TemplateContextConfig) *TemplateContext

NewContextWithConfig creates a new context with configuration.

If configuration is nil, it will use default configuration.

type TemplateAndText 

type TemplateAndText struct {
	// Text is the actual template that got parsed by _template.Template_.
	Text string
	// Template is the instance of the parsed _Text_ including functions.
	Template *template.Template
}

TemplateAndText is a wrapper of _template.Template_ but also includes the original text representation of the template and not just the parsed tree.

type TemplateContext 

type TemplateContext struct {

	// File is the complete file. This property is always present.
	//
	// For package and imports, this is the only one to access
	File *goparser.GoFile
	// Package where the `File` resides under. Most of the time
	// is `Package` and `File` the same since rendering is done
	// on package level.
	Package *goparser.GoPackage
	// Module for the context
	Module *goparser.GoModule
	// Struct is the current GoStruct
	Struct *goparser.GoStruct
	// Function is the current function
	Function *goparser.GoStructMethod
	// Interface is the current GoInterface
	Interface *goparser.GoInterface
	// TypeDefVar is current variable type definition
	TypeDefVar *goparser.GoCustomType
	// TypedefFun is current function type definition.
	TypeDefFunc *goparser.GoMethod
	// VarAssignment is current variable assignment using var keyword
	VarAssignment *goparser.GoAssignment
	// ConstAssignment is current const definition and value assignment
	ConstAssignment *goparser.GoAssignment
	// Config contains the configuration of this context.
	Config *TemplateContextConfig
	// Index is configuration to render the index template
	Index *IndexConfig
	// Receiver is the current receivers to be rendered.
	Receiver []*goparser.GoStructMethod
	// Docs is a map that contains filepaths to various asciidoc documents
	// that can be included.
	//
	// .Available Documents
	// |===
	// |Name |Comment
	//
	// |package-overview
	// |This is a absolute path to a overview document for the current package.
	//
	// |===
	Docs map[string]string
	// contains filtered or unexported fields
}

TemplateContext is a context that may be used to render a GoFile. Depending on the template, different fields are populated in this struct.

func (*TemplateContext) Clone 

func (t *TemplateContext) Clone(clean bool) *TemplateContext

Clone will clone the context.

func (*TemplateContext) Creator 

func (t *TemplateContext) Creator() *Template

Creator returns the template created this context.

func (*TemplateContext) DefaultIndexConfig 

func (t *TemplateContext) DefaultIndexConfig(overrides string) *IndexConfig

DefaultIndexConfig creates a default index configuration that may be used in RenderIndex function.

The overrides are specifies as a json document, only properties set in the JSON document will override default IndexConfig.

func (*TemplateContext) RenderConstDeclaration 

func (t *TemplateContext) RenderConstDeclaration(wr io.Writer, a *goparser.GoAssignment) *TemplateContext

RenderConstDeclaration will render a single const declaration section onto the provided writer.

func (*TemplateContext) RenderConstDeclarations 

func (t *TemplateContext) RenderConstDeclarations(wr io.Writer) *TemplateContext

RenderConstDeclarations will render all const declarations for GoFile/GoPackage onto the provided writer.

func (*TemplateContext) RenderFunction 

func (t *TemplateContext) RenderFunction(wr io.Writer, f *goparser.GoStructMethod) *TemplateContext

RenderFunction will render a single function section onto the provided writer.

func (*TemplateContext) RenderFunctions 

func (t *TemplateContext) RenderFunctions(wr io.Writer) *TemplateContext

RenderFunctions will render all functions for GoFile/GoPackage onto the provided writer.

func (*TemplateContext) RenderImports 

func (t *TemplateContext) RenderImports(wr io.Writer) *TemplateContext

RenderImports will render the imports section onto the provided writer.

func (*TemplateContext) RenderIndex 

func (t *TemplateContext) RenderIndex(wr io.Writer, ic *IndexConfig) *TemplateContext

RenderIndex will render the complete index page for all GoFiles/GoPackages onto the provided writer.

If nil is provided as IndexConfig it will use the default config.

func (*TemplateContext) RenderInterface 

func (t *TemplateContext) RenderInterface(wr io.Writer, i *goparser.GoInterface) *TemplateContext

RenderInterface will render a single interface section onto the provided writer.

func (*TemplateContext) RenderInterfaces 

func (t *TemplateContext) RenderInterfaces(wr io.Writer) *TemplateContext

RenderInterfaces will render all interfaces for GoFile/GoPackage onto the provided writer.

func (*TemplateContext) RenderPackage 

func (t *TemplateContext) RenderPackage(wr io.Writer) *TemplateContext

RenderPackage will render the package defintion onto the provided writer.

Depending on if a package overview asciidoc document is found it will prioritize that before the go package documentation. Hence it will use either _PackageTemplate_ or _PackageIncludeOverviewTemplate_ depending if found a ascii doc overview document.

func (*TemplateContext) RenderPrivate 

func (t *TemplateContext) RenderPrivate() *TemplateContext

RenderPrivate will enable non exported to be rendered.

func (*TemplateContext) RenderReceiverFunctions 

func (t *TemplateContext) RenderReceiverFunctions(wr io.Writer, receiver string) *TemplateContext

RenderReceiverFunctions will render all receiver functions for a given receiver, albeit a custom type or a struct.

func (*TemplateContext) RenderStruct 

func (t *TemplateContext) RenderStruct(wr io.Writer, s *goparser.GoStruct) *TemplateContext

RenderStruct will render a single struct section onto the provided writer.

func (*TemplateContext) RenderStructs 

func (t *TemplateContext) RenderStructs(wr io.Writer) *TemplateContext

RenderStructs will render all structs for GoFile/GoPackage onto the provided writer.

func (*TemplateContext) RenderTypeDefFunc 

func (t *TemplateContext) RenderTypeDefFunc(wr io.Writer, td *goparser.GoMethod) *TemplateContext

RenderTypeDefFunc will render a single typedef section onto the provided writer.

func (*TemplateContext) RenderTypeDefFuncs 

func (t *TemplateContext) RenderTypeDefFuncs(wr io.Writer) *TemplateContext

RenderTypeDefFuncs will render all type definitions for GoFile/GoPackage onto the provided writer.

func (*TemplateContext) RenderVarDeclaration 

func (t *TemplateContext) RenderVarDeclaration(wr io.Writer, a *goparser.GoAssignment) *TemplateContext

RenderVarDeclaration will render a single variable declaration section onto the provided writer.

func (*TemplateContext) RenderVarDeclarations 

func (t *TemplateContext) RenderVarDeclarations(wr io.Writer) *TemplateContext

RenderVarDeclarations will render all variable declarations for GoFile/GoPackage onto the provided writer.

func (*TemplateContext) RenderVarTypeDef 

func (t *TemplateContext) RenderVarTypeDef(wr io.Writer, td *goparser.GoCustomType) *TemplateContext

RenderVarTypeDef will render a single variable typedef section onto the provided writer.

func (*TemplateContext) RenderVarTypeDefs 

func (t *TemplateContext) RenderVarTypeDefs(wr io.Writer) *TemplateContext

RenderVarTypeDefs will render all variable type definitions for GoFile/GoPackage onto the provided writer.

type TemplateContextConfig 

type TemplateContextConfig struct {
	// IncludeMethodCode determines if the code is included in the documentation or not.
	// Default not included.
	IncludeMethodCode bool
	// PackageOverviewPaths paths to search for package overview relative the package path.
	//
	// It searches the order as they appear in this array until found, then terminates. It is
	// not possible to have two _*.adoc_ inclusions.
	//
	// .Example Paths
	// |===
	// |Example |Comment
	//
	// |overview.adoc
	// |This expects the overview.adoc to be in the same folders as the other go files in the package.
	//
	// |_design/package-summary.adoc
	// |This tells the renderer to look for _package-summary.adoc_ in _package path/_design_ folder.
	//
	// |===
	PackageOverviewPaths []string
	// Private indicates if it shall include private as well. By default only Exported is rendered.
	Private bool
}

TemplateContextConfig contains configuration parameters how templates renders the content and the TemplateContexts behaves.

type TemplateType 

type TemplateType string

TemplateType specifies the template type 

const (
	// IndexTemplate is a template that binds all generated asciidoc files into one single index file
	// by referencing (or appending to this file).
	IndexTemplate TemplateType = "index"
	// PackageTemplate specifies that the template is a package
	PackageTemplate TemplateType = "package"
	// ImportTemplate specifies that the template renders a import
	ImportTemplate TemplateType = "import"
	// FunctionsTemplate is a template to render all functions for a given context (package, file)
	FunctionsTemplate TemplateType = "functions"
	// FunctionTemplate is a template to render a function
	FunctionTemplate TemplateType = "function"
	// InterfacesTemplate is a template to render a all interface defintions for a given context (package, file)
	InterfacesTemplate TemplateType = "interfaces"
	// InterfaceTemplate is a template to render a interface definition
	InterfaceTemplate TemplateType = "interface"
	// StructsTemplate specifies that the template renders all struct definitions for a given context (package, file)
	StructsTemplate TemplateType = "structs"
	// StructTemplate specifies that the template renders a struct definition
	StructTemplate TemplateType = "struct"
	// CustomVarTypeDefsTemplate is a template to render all variable type definitions for a given context (package, file)
	CustomVarTypeDefsTemplate TemplateType = "typedefvars"
	// CustomVarTypeDefTemplate is a template to render a type definition of a variable
	CustomVarTypeDefTemplate TemplateType = "typedefvar"
	// CustomFuncTypeDefsTemplate is a template to render all function type definitions for a given context (package, file)
	CustomFuncTypeDefsTemplate TemplateType = "typedeffuncs"
	// CustomFuncTypeDefTemplate is a template to render a function type definition
	CustomFuncTypeDefTemplate TemplateType = "typedeffunc"
	// VarDeclarationsTemplate is a template to render all variable definitions for a given context (package, file)
	VarDeclarationsTemplate TemplateType = "vars"
	// VarDeclarationTemplate is a template to render a variable definition
	VarDeclarationTemplate TemplateType = "var"
	// ConstDeclarationsTemplate is a template to render all const declaration entries for a given context (package, file)
	ConstDeclarationsTemplate TemplateType = "consts"
	// ConstDeclarationTemplate is a template to render a const declaration entry
	ConstDeclarationTemplate TemplateType = "const"
	// ReceiversTemplate is a template that renders receivers functions
	ReceiversTemplate TemplateType = "receivers"
)

func (TemplateType) String 

func (tt TemplateType) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.