Documentation
¶
Overview ¶
Package docs provides version-aware Markdown retrieval for Atlas tools.
Index ¶
- Constants
- type CachingProvider
- type Document
- type FSProvider
- type FallbackProvider
- type GitProvider
- type Manifest
- type Provider
- type SearchOptions
- type SearchResult
- type Section
- func HeadingTree(doc Document) []Section
- func ListHeadings(ctx context.Context, provider Provider, path string) ([]Section, error)
- func ParseSections(doc Document) []Section
- func ParseSectionsWithoutTitle(doc Document) []Section
- func ReadNeighborhood(ctx context.Context, provider Provider, path string, heading string, ...) ([]Section, error)
- func ReadSection(ctx context.Context, provider Provider, path string, heading string, ...) (Section, bool, error)
- type StaticProvider
Constants ¶
const DefaultRef = "main"
DefaultRef is the docs branch Atlas tracks when no explicit ref is configured.
const DefaultRepo = "https://github.com/goforj/docs.git"
DefaultRepo is the canonical GoForj docs repository Atlas reads from.
const EnvCacheDir = "GOFORJ_ATLAS_DOCS_CACHE"
EnvCacheDir overrides the local cache used for cloned docs.
const EnvPath = "GOFORJ_DOCS_PATH"
EnvPath is the development override for live GoForj docs.
const EnvRef = "GOFORJ_ATLAS_DOCS_REF"
EnvRef selects the branch, tag, or revision used for cached docs.
const EnvRepo = "GOFORJ_ATLAS_DOCS_REPO"
EnvRepo overrides the hosted docs repository used for cached docs.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CachingProvider ¶ added in v0.1.1
type CachingProvider struct {
Provider Provider
// contains filtered or unexported fields
}
CachingProvider loads docs once and serves them from memory afterward.
type Document ¶
type Document struct {
Path string `json:"path"`
Title string `json:"title"`
Content string `json:"content"`
Tags []string `json:"tags,omitempty"`
Meta map[string]string `json:"meta,omitempty"`
}
Document is one Markdown document in a docs set.
type FSProvider ¶
FSProvider loads Markdown docs from a filesystem directory.
type FallbackProvider ¶ added in v0.1.1
type FallbackProvider struct {
Providers []Provider
}
FallbackProvider tries docs providers in order until one returns documents.
type GitProvider ¶ added in v0.1.1
type GitProvider struct {
CacheDir string
Repo string
Ref string
Version string
Refresh bool
// contains filtered or unexported fields
}
GitProvider loads GoForj docs from a local git cache.
func NewGitProvider ¶ added in v0.1.1
func NewGitProvider(version string) *GitProvider
NewGitProvider returns a git-backed docs provider with normal GoForj defaults.
type Manifest ¶
type Manifest struct {
Version string `json:"version"`
Revision string `json:"revision"`
Ref string `json:"ref,omitempty"`
Commit string `json:"commit,omitempty"`
GoForjVersion string `json:"goforj_version,omitempty"`
GeneratedAt string `json:"generated_at,omitempty"`
}
Manifest describes the docs set exposed by Atlas.
type Provider ¶
type Provider interface {
// Manifest returns version and revision information for the docs set.
Manifest(context.Context) (Manifest, error)
// Documents returns the Markdown documents available to Atlas.
Documents(context.Context) ([]Document, error)
}
Provider supplies versioned documentation to Atlas.
func DefaultProvider ¶ added in v0.1.1
DefaultProvider returns Atlas docs using a local override or cached git docs.
func ProviderFromEnv ¶
ProviderFromEnv returns an FSProvider when GOFORJ_DOCS_PATH is set.
type SearchOptions ¶
SearchOptions controls docs search.
type SearchResult ¶
type SearchResult struct {
Path string `json:"path"`
Title string `json:"title"`
Heading string `json:"heading"`
Snippet string `json:"snippet"`
Score int `json:"score"`
}
SearchResult is one ranked docs search hit.
func ExplainAPI ¶
ExplainAPI maps common GoForj commands and paths to docs sections.
func Search ¶
func Search(ctx context.Context, provider Provider, opts SearchOptions) ([]SearchResult, error)
Search finds relevant docs sections.
type Section ¶
type Section struct {
Path string `json:"path"`
Title string `json:"title"`
Heading string `json:"heading"`
Level int `json:"level"`
Body string `json:"body"`
}
Section is one Markdown heading section.
func HeadingTree ¶
HeadingTree returns the headings for a document.
func ListHeadings ¶
ListHeadings returns the heading tree for path.
func ParseSections ¶
ParseSections parses a Markdown document into heading sections.
func ParseSectionsWithoutTitle ¶
ParseSectionsWithoutTitle exists to avoid recursive title discovery.
type StaticProvider ¶
StaticProvider is an in-memory docs provider for fixed or test docs.
Source Files