Documentation
¶
Overview ¶
Package generate provides output generation from APIStyleSpec.
This package can generate various outputs from a style specification:
- Markdown documentation (human-readable style guide)
- Spectral YAML (linting ruleset for Spectral/vacuum)
Usage:
spec, _ := profile.Load("azure")
markdown, err := generate.Markdown(spec, nil)
spectral, err := generate.Spectral(spec, nil)
The generated outputs can be written to files or served via API.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Markdown ¶
func Markdown(spec *types.APIStyleSpec, opts *MarkdownOptions) (string, error)
Markdown generates Markdown documentation from an APIStyleSpec.
func Spectral ¶
func Spectral(spec *types.APIStyleSpec, opts *SpectralOptions) (string, error)
Spectral generates a Spectral-compatible YAML ruleset from an APIStyleSpec.
func WriteMkDocs ¶ added in v0.3.0
func WriteMkDocs(result *MkDocsResult, outputDir string) error
WriteMkDocs writes the MkDocs site to a directory.
Types ¶
type MarkdownOptions ¶
type MarkdownOptions struct {
// IncludeTOC adds a table of contents.
IncludeTOC bool
// IncludeExamples includes good/bad examples.
IncludeExamples bool
// IncludeRationale includes rule rationales.
IncludeRationale bool
// IncludeReferences includes external references.
IncludeReferences bool
// IncludeConformance includes conformance level details.
IncludeConformance bool
// IncludeMetadata includes spec metadata.
IncludeMetadata bool
// IncludeIntroduction includes the introduction section.
IncludeIntroduction bool
// IncludePrinciples includes design principles.
IncludePrinciples bool
// IncludePatterns includes API design patterns.
IncludePatterns bool
// IncludeGlossary includes the glossary.
IncludeGlossary bool
// IncludeDescription includes rule descriptions.
IncludeDescription bool
// SeverityEmojis uses emojis for severity indicators.
SeverityEmojis bool
}
MarkdownOptions configures Markdown generation.
func DefaultMarkdownOptions ¶
func DefaultMarkdownOptions() *MarkdownOptions
DefaultMarkdownOptions returns options with all features enabled.
type MkDocsOptions ¶ added in v0.3.0
type MkDocsOptions struct {
// SiteName is the MkDocs site name.
SiteName string
// SiteURL is the base URL for the site.
SiteURL string
// RepoURL is the source repository URL.
RepoURL string
// Theme is the MkDocs theme (default: material).
Theme string
// IncludeSearch enables search functionality.
IncludeSearch bool
// SplitCategories creates separate pages per category.
SplitCategories bool
// SplitPatterns creates separate pages per pattern.
SplitPatterns bool
// MarkdownOptions for generating individual pages.
MarkdownOptions *MarkdownOptions
}
MkDocsOptions configures MkDocs site generation.
func DefaultMkDocsOptions ¶ added in v0.3.0
func DefaultMkDocsOptions() *MkDocsOptions
DefaultMkDocsOptions returns default MkDocs configuration.
type MkDocsResult ¶ added in v0.3.0
type MkDocsResult struct {
// Config is the mkdocs.yml content.
Config string
// Pages maps file paths (relative to docs/) to content.
Pages map[string]string
}
MkDocsResult contains the generated MkDocs site files.
func MkDocs ¶ added in v0.3.0
func MkDocs(spec *types.APIStyleSpec, opts *MkDocsOptions) (*MkDocsResult, error)
MkDocs generates a complete MkDocs site structure from an APIStyleSpec.
type SpectralOptions ¶
type SpectralOptions struct {
// IncludeDisabled includes disabled rules (commented out).
IncludeDisabled bool
// IncludeDescriptions adds rule descriptions as comments.
IncludeDescriptions bool
// SkipNonEnforceable skips rules without enforcement config.
SkipNonEnforceable bool
}
SpectralOptions configures Spectral ruleset generation.
func DefaultSpectralOptions ¶
func DefaultSpectralOptions() *SpectralOptions
DefaultSpectralOptions returns options with sensible defaults.
Source Files