documents

README

documents

The documents package is used for locating and parsing Roblox API documentation files.

Documentation

Overview

The documents page queries resources for document fragments.

A resource is a hierarchical construct that contains Sections, which is usually a directory or file.

Index

• func FindGit() string
• func GitRead(git, file string) (b []byte, err error)
• type Countable
• type DirectorySection
  • func NewDirectorySection(path string, handlers ...FileHandler) *DirectorySection
  • func (s DirectorySection) Name() string
  • func (s DirectorySection) Query(name ...string) Section
  • func (s DirectorySection) QueryAll(name string) (sections []Section)
  • func (s DirectorySection) Render() template.HTML
  • func (s DirectorySection) Subsections() []Section
• type FileHandler
• type Headingable
• type Linkable
• type MarkdownHandler
  • func (h MarkdownHandler) FileHandler(dir string, info os.FileInfo, query string) Section
• type MarkdownSection
  • func NewMarkdownSection(document *ast.Document) *MarkdownSection
  • func (s *MarkdownSection) AdjustLevels(level int)
  • func (s *MarkdownSection) Count() int
  • func (s *MarkdownSection) HeadingID() string
  • func (s *MarkdownSection) Links(walk func(string))
  • func (s *MarkdownSection) Name() string
  • func (s *MarkdownSection) Query(name ...string) Section
  • func (s *MarkdownSection) Render() template.HTML
  • func (s *MarkdownSection) RootLevel() (level int)
  • func (s *MarkdownSection) SetHeadingID(id string)
  • func (s *MarkdownSection) SetLinks(walk func(string) string)
  • func (s *MarkdownSection) SetRender(renderer markdown.Renderer)
  • func (s *MarkdownSection) Subsections() []Section
• type Section
  • func MarkdownFileHandler(dir string, info os.FileInfo, query string) Section

Functions

func FindGit

func FindGit() string

FindGit returns the path to the git executable, or an empty string if it is not available.

func GitRead

func GitRead(git, file string) (b []byte, err error)

GitRead attempts to read the most recently committed content of a file.

Types

type Countable

type Countable interface {
	Section
	// Count returns the number of elements in the section.
	Count() int
}

Countable extends a Section by representing a document with countable content.

type DirectorySection

type DirectorySection struct {
	Path     string
	Handlers []FileHandler
}

DirectorySection represents a directory in a file system.

func NewDirectorySection

func NewDirectorySection(path string, handlers ...FileHandler) *DirectorySection

NewDirectorySection returns a new DirectorySection from the given path. Optional handlers may be specified.

func (DirectorySection) Name

func (s DirectorySection) Name() string

func (DirectorySection) Query

func (s DirectorySection) Query(name ...string) Section

Query queries a file of the given name from the directory. For each file of the directory, each FileHandler is called in order. If a handler returns a non-nil Section, then that section becomes the result.

If no handler returns a section, and the current file is a directory whose name matches the query, then the result will be a DirectorySection that inherits the handlers of the current section.

Subsequent names are queried from the resulting section, if one exists.

func (DirectorySection) QueryAll

func (s DirectorySection) QueryAll(name string) (sections []Section)

QueryAll is similar to Query, but returns all sections matching the first name.

func (DirectorySection) Render

func (s DirectorySection) Render() template.HTML

func (DirectorySection) Subsections

func (s DirectorySection) Subsections() []Section

type FileHandler

type FileHandler func(dir string, info os.FileInfo, query string) Section

FileHandler hooks into a directory query, transforming a file within the directory into a Section.

The dir argument is the directory in which the file is located. The info argument is information about the current file. The query argument is the current query being made.

The handler should return nil when the query does not match, or the information given about the file is inapplicable.

type Headingable

type Headingable interface {
	Section
	// AdjustLevels offsets the levels of all headings in the outline, such
	// that RootLevel returns the given value.
	AdjustLevels(level int)
	// RootLevel returns the level of the root heading. This is defined as one
	// level less than the lowest heading level present in the outline.
	RootLevel() int
	// HeadingID returns the ID attribute of the heading.
	HeadingID() string
	// SetHeadingID sets the ID attribute of the heading.
	SetHeadingID(string)
}

Headingable extends a Section by representing an outline with traversable headings.

type Linkable

type Linkable interface {
	Section
	// Links receives a walk function, which receives a link. The function is
	// applied to all links within the section, which can include those within
	// subsections.
	Links(walk func(link string))
	// SetLinks receives a walk function, which receives a link and returns an
	// adjusted link. The function is applied to all links within the section,
	// which can include those within subsections.
	SetLinks(walk func(link string) string)
}

Linkable extends a Section by representing a document with traversable reference links.

type MarkdownHandler

type MarkdownHandler struct {
	// UseGit sets whether the handler is aware of git. If so, only committed
	// content will be used. That is, untracked files are ignored, and only
	// committed modifications to a file are used.
	UseGit bool

	// StripComments sets whether comments will be removed.
	StripComments bool
}

MarkdownHandler has a configurable FileHandler that parses a markdown file.

func (MarkdownHandler) FileHandler

func (h MarkdownHandler) FileHandler(dir string, info os.FileInfo, query string) Section

FileHandler is a FileHandler that parses a markdown file.

type MarkdownSection

type MarkdownSection struct {
	// Heading is the name of the outer heading enclosing the section.
	Heading string
	// Level is the level of the outer heading enclosing the section.
	Level int
	// ID is "id" attribute of the outer heading enclosing the section.
	ID string
	// Document is the raw content of the section.
	Document *ast.Document
	// HeadingNode is the node of the outer heading enclosing the section.
	HeadingNode *ast.Heading
	// Sections contains each subsection.
	Sections []*MarkdownSection
	// Renderer specifies a custom renderer to use when rendering the section
	// content to HTML. If nil, the default HTML renderer is used.
	Renderer markdown.Renderer
}

MarkdownSection represents a portion of a markdown document. Sections are delimited by headings.

func NewMarkdownSection

func NewMarkdownSection(document *ast.Document) *MarkdownSection

NewMarkdownSection creates a new MarkdownSection from an ast.Document.

Subsections are created by outlining the headings of the document; each subheading corresponds to a subsection, which can be queried by the name of the heading. Also included are "orphaned" sections, which enclose parts of the document without a heading. These can be queried with an empty string.

Only headings which are direct children of the document are outlined. Note that all subsections share the same underlying document. i.e. if a node within a section is modified, the parent section will be affected.

func (*MarkdownSection) AdjustLevels

func (s *MarkdownSection) AdjustLevels(level int)

AdjustLevel adjusts the level of each heading node in the document such that RootLevel returns the given value. This does not affect the Level field of the section and subsections.

func (*MarkdownSection) Count

func (s *MarkdownSection) Count() int

func (*MarkdownSection) HeadingID

func (s *MarkdownSection) HeadingID() string

func (*MarkdownSection) Links

func (s *MarkdownSection) Links(walk func(string))

func (*MarkdownSection) Name

func (s *MarkdownSection) Name() string

func (*MarkdownSection) Query

func (s *MarkdownSection) Query(name ...string) Section

func (*MarkdownSection) Render

func (s *MarkdownSection) Render() template.HTML

func (*MarkdownSection) RootLevel

func (s *MarkdownSection) RootLevel() (level int)

RootLevel returns the level of the root heading, which is defined as one less than the lowest heading level present in the document. Returns -1 if there are no headings in the document. Heading levels are assumed to be positive.

func (*MarkdownSection) SetHeadingID

func (s *MarkdownSection) SetHeadingID(id string)

func (*MarkdownSection) SetLinks

func (s *MarkdownSection) SetLinks(walk func(string) string)

func (*MarkdownSection) SetRender

func (s *MarkdownSection) SetRender(renderer markdown.Renderer)

SetRenderer sets the Renderer field of the section and all subsections.

func (*MarkdownSection) Subsections

func (s *MarkdownSection) Subsections() []Section

type Section

type Section interface {
	// Name is the name of the section.
	Name() string
	// Query retrieves the subsection referred to by the given name list. Each
	// successive name refers to a subsection of the previous. Returns nil if
	// the subsection was not found.
	Query(name ...string) Section
	// Subsections returns a list of the subsections within the current
	// section.
	Subsections() []Section
	// Render returns the content rendered to HTML.
	Render() template.HTML
}

Section represents a queryable portion of a resource.

func MarkdownFileHandler

func MarkdownFileHandler(dir string, info os.FileInfo, query string) Section

MarkdownFileHandler is a FileHandler that parses a markdown file.