Documentation
¶
Index ¶
- func Serialize(docs *Documentation) (string, error)
- func SortNodesByName(node *Node)
- type ContentSelector
- type Documentation
- type LinkSubstitute
- type LinkSubstitutes
- type LinksMatchers
- type LocalityDomain
- type LocalityDomainMap
- type LocalityDomainValue
- type Node
- func (n *Node) AddStats(s ...*Stat)
- func (n *Node) GetRootNode() *Node
- func (n *Node) GetStats() []*Stat
- func (n *Node) Parent() *Node
- func (n *Node) Parents() []*Node
- func (n *Node) Peers() []*Node
- func (n *Node) RelativePath(to *Node) string
- func (n *Node) SetParent(node *Node)
- func (n *Node) SetParentsDownwards()
- type NodeSelector
- type Stat
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SortNodesByName ¶ added in v0.1.0
func SortNodesByName(node *Node)
SortNodesByName recursively sorts all child nodes in the node hierarchy by node Name
Types ¶
type ContentSelector ¶
type ContentSelector struct {
// URI of a document
Source string `yaml:"source,omitempty"`
// Optional filtering expression that selects content from the document content
// Omiting this file will select the whole document content.
Selector *string `yaml:"selector,omitempty"`
}
ContentSelector specifies a document node content target
type Documentation ¶
type Documentation struct {
// Root is the root node of this documentation structure
Root *Node `yaml:"root"`
// Variables are a set of key-value entries, where the key is the variable name
// and the value is a node template. Nodes defined as variables can be resused
// by reference throughout the documentation structure to minimise duplicate
// node definitions. A reference to a variable is in the format `$variable-name`,
// where `varaible-name` is a key in this Variables map structure.
//
// Note: WiP - proposed, not implemented yet.
Variables map[string]*Node `yaml:"variables,omitempty"`
// LocalityDomain defines the scope of the downloadable resources
// for this structure
LocalityDomain *LocalityDomain `yaml:"localityDomain,omitempty"`
}
Documentation is a documentation structure that can be serialized and deserialized and parsed into a model supporting the tasks around building a concrete documentaiton bundle.
type LinkSubstitute ¶ added in v0.2.0
type LinkSubstitute struct {
Text *string `yaml:"text,omitempty"`
Destination *string `yaml:"destination,omitempty"`
Title *string `yaml:"title,omitempty"`
}
LinkSubstitute comprises subtitutes for various link details commonly found in markup
type LinkSubstitutes ¶ added in v0.2.0
type LinkSubstitutes map[string]*LinkSubstitute
LinkSubstitutes is the mapping between absolute links and substitutions for them
type LinksMatchers ¶ added in v0.2.0
type LinksMatchers struct {
// Include is a list of regular expressions that will be matched to every
// link that is candidate for download to determine whether it is
// eligible. The links to match are absolute.
// Include can be used in conjunction with Exclude when it is easier/
// preferable to deny all resources and allow selectively.
// Include can be used in conjunction with localityDomain to add
// additional resources not in the domain.
Include []string `yaml:"include,omitempty"`
// Exclude is a list of regular expression that will be matched to every
// link that is candidate for download to determine whether it is
// not eligible. The links to match are absolute.
// Use Exclude to further constrain the set of downloaded resources
// that are in a locality domain.
Exclude []string `yaml:"exclude,omitempty"`
}
LinksMatchers defines links exclusion/inclusion patterns
type LocalityDomain ¶
type LocalityDomain struct {
LocalityDomainMap `yaml:",inline"`
// DownloadSubstitutes is an optional map of resource names in this
// locality domain and their substitutions. Use it to override the
// default downloads naming:
// - An exact download name mapped to a download resource will be used
// to name that resources when downloaded.
// - An expression with substitution variables can be used
// to change the default pattern for generating donwloaded resouce
// names, which is $uuid.
// The supported variables are:
// - $name: the original name of the resouce
// - $path: the original path of the resource in this domain (may be empty)
// - $uuid: the identifier generated f=or the downloaded resource
// - $ext: the extension of the original resource (may be "")
// Example expression: $name-$uuid
DownloadSubstitutes map[string]string `yaml:"downloadSubstitutes,omitempty"`
}
LocalityDomain contains the entries defining a locality domain scope. Each entry is a mapping between a domain, such as github.com/gardener/gardener, and a path in it that defines "local" resources. Documents referenced by documentation node structure are always part of the locality domain. Other resources referenced by those documents are checked against the path hierarchy of locality domain entries to determine how they will be processed.
type LocalityDomainMap ¶ added in v0.2.0
type LocalityDomainMap map[string]*LocalityDomainValue
LocalityDomainMap maps domains such as github.com/gardener/gardener to LocalityDomainValues
type LocalityDomainValue ¶
type LocalityDomainValue struct {
// Version sets the version of the resources that will
// be referenced in this domain. Download targets and
// absolute links in documents referenced by the structure
// will be rewritten to match this version
Version string `yaml:"version"`
// Path is the relative path inside a domain that contains
// resources considered 'local' that will be downloaded.
Path string `yaml:"path"`
LinksMatchers `yaml:",inline"`
}
LocalityDomainValue encapsulates the memebers of a LocalityDomain entry value
type Node ¶
type Node struct {
// Name is the name of this node. If omited, the name is the resource name from
// Source as reported by an eligible ResourceHandler's Name() method.
// Node with multiple Source entries require name.
Name string `yaml:"name,omitempty"`
// A reference to the parent of this node, unless it is the root. Unexported and
// assigned internally when the node structure is resolved. Not marshalled.
// Title is the title for a node displayed to human users
Title string `yaml:"title,omitempty"`
// Source is a sequence of path specifications to locate the resources
// that represent this document node. There must be at minimum one. When
// they are multiple, the resulting document is an aggregation of the
// material located at each path.
//
// A source path specification entries are in the following format:
// `path[#{semantic-block-selector}]`, where:
// - `path` is a valid resource locator for a document.
// - `semantic-block-selector`is an expression that selects semantic block
// elements from the document similiar to CSS selectors (Note: WiP - proposed,
// not implemented yet.).
//
// Examples:
// - A single file
// `source: ["path/a/b/c/file.md"]`
//
// - Two files in order to construct a new document
// `source: ["path1/a/b/c/file1.md",
// "path2/e/f/g/file2.md"]`
//
// - A file and the section under the first heading level 1 from another file
// in that order to construct a new document.
// Note: WiP - proposed, not implemented yet.
// `source: ["path1/a/b/c/file1.md",
// "path2/e/f/g/file2.md#{h1:first-of-type}"]`
ContentSelectors []ContentSelector `yaml:"contentSelectors,omitempty"`
// Nodes is an array of nodes that are subnodes (children) of this node
//
// Note: For a non-strict alternative for specifying child nodes, refer to
// `NodesSelector`
Nodes []*Node `yaml:"nodes,omitempty"`
// NodesSelector is a structure modeling an existing structure of documents at a
// location that can be further filtered by their metadata propertis and set as
// child nodes to this node. This is an alternative to explicitly setting child
// nodes structure resource paths with `Nodes`.
// Note: WiP - proposed, not implemented yet.
NodeSelector *NodeSelector `yaml:"nodesSelector,omitempty"`
// Properties are a map of arbitary, key-value pairs to model custom,
// untyped node properties. They could be used to instruct specific ResourceHandlers
// and the serialization of the Node. For example the properyies member could be
// used to set the front-matter to markdowns for front-matter aware builders such
// as Hugo.
Properties map[string]interface{} `yaml:"properties,omitempty"`
*LocalityDomain `yaml:"localityDomain,omitempty"`
// LinksSubstitutes is an optional map of links and their
// substitutions. Use it to override the default handling of those
// links in documents referenced by this node's contentSelector:
// - An empty substitution string ("") removes a link markdown.
// It leaves only its text component in the document for links
// and nothing for images.
// This applies only to markdown for links and images.
// - A fixed string that will replace the whole original link
// destination.
// The keys in the substitution map are matched against documents
// links as exact string matches. The document links are converted to
// their absolute form for the match
// TODO: update this doc
LinksSubstitutes LinkSubstitutes `yaml:"linksSubstitutes,omitempty"`
// contains filtered or unexported fields
}
Node is a recursive, tree data structure representing documentation model.
func FindNodeByContentSource ¶
FindNodeByContentSource traverses up and then all around the tree paths in the node's documentation strcuture, looking for a node that has contentSource path nodeContentSource
func (*Node) GetRootNode ¶
GetRootNode returns the root node in the parents path for a node object n
func (*Node) Parents ¶
Parents returns the path of nodes from this nodes parent to the root of the hierarchy
func (*Node) RelativePath ¶
RelativePath returns the relative path between two nodes on the same tree, formatted with `..` for ancestors path if any and `.` for current node in relative path to descendant. The function can also calculate path to a node on another branch
func (*Node) SetParentsDownwards ¶
func (n *Node) SetParentsDownwards()
SetParentsDownwards walks recursively the hierarchy under this node to set the parent property.
type NodeSelector ¶
type NodeSelector struct {
// Path is a resource locator to a set of files, i.e. to a resource container.
Path string `yaml:"path"`
// Depth a maximum depth of the recursion. If omitted or less than 0, the
// constraint is not considered
Depth int64 `yaml:"depth,omitempty"`
// Annotation is an optional expression, filtering documents located at `Path`
// by their metadata properties. Markdown metadata is commonly provisioned as
// `front-matter` block at the head of the document delimited by comment
// tags (`---`).
Annotation string `yaml:"annotation,omitempty"`
}
NodeSelector is an specification for selecting subnodes (children) for a node. The order in which the documents are selected is not guaranteed. The interpreters of NodeSelectors can make use of the resource metadata or other sources to construct and populate child Nodes dynamically.
Example:
- Select all documents located at path/a/b/c that have front-matter property `type` with value `faq`: ``` nodesSelector: { path: "path/a/b/c", annotation: "type:faq" } ``` will select markdown documents located at path/a/b/c with front-matter: --- type: faq ---
Note: WiP - proposed, not implemented yet.
Source Files