generate

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

• func Markdown(spec *types.APIStyleSpec, opts *MarkdownOptions) (string, error)
• func Spectral(spec *types.APIStyleSpec, opts *SpectralOptions) (string, error)
• type MarkdownOptions
  • func DefaultMarkdownOptions() *MarkdownOptions
• type SpectralOptions
  • func DefaultSpectralOptions() *SpectralOptions

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.

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

	// 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 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.