Documentation
¶
Index ¶
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
// 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 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 is the range
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 LocalityDomain ¶
type LocalityDomain map[string]*LocalityDomainValue
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 hwo they will be processed.
type LocalityDomainValue ¶
LocalityDomainValue encapsulates the memebers of a LocalityDomain entry value
type Node ¶
type Node struct {
// 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"`
// 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"`
// 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