printingpress

package
v0.0.63 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 6, 2026 License: Apache-2.0 Imports: 57 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AggregateBuildModeFull  = "full"
	AggregateBuildModeFast  = "fast"
	AggregateBuildModeWatch = "watch"
)
View Source
const (
	AggregateProgressKindPool = "pool"

	AggregateProgressStatusQueued    = "queued"
	AggregateProgressStatusRunning   = "running"
	AggregateProgressStatusCompleted = "completed"
	AggregateProgressStatusSkipped   = "skipped"
)
View Source
const (
	HTMLAssetModePortable = "portable"
	HTMLAssetModeServed   = "served"
)

Variables

View Source
var (
	// ErrNoSourceInput is returned when no source is provided to a constructor.
	ErrNoSourceInput = errors.New("printingpress: exactly one source input is required")
	// ErrMultipleSourceInputs is returned when more than one source is configured.
	ErrMultipleSourceInputs = errors.New("printingpress: only one source input may be configured")
	// ErrInvalidBaseURL is returned when BaseURL is not a supported hosted docs root.
	ErrInvalidBaseURL = errors.New("printingpress: base URL is invalid")
	// ErrInvalidBasePath is returned when BasePath cannot be resolved to a valid directory.
	ErrInvalidBasePath = errors.New("printingpress: base path is invalid")
	// ErrInvalidOutputDir is returned when OutputDir cannot be resolved.
	ErrInvalidOutputDir = errors.New("printingpress: output directory is invalid")
	// ErrNoDrDocument is returned when a doctor model could not be produced.
	ErrNoDrDocument = errors.New("printingpress: doctor model is required")
	// ErrNoV3Document is returned when a doctor model has no libopenapi v3 document.
	ErrNoV3Document = errors.New("printingpress: doctor model has no V3 document")
	// ErrNoOutputDir is returned when no output directory can be resolved.
	ErrNoOutputDir = errors.New("printingpress: output directory is required")
	// ErrNilSite is returned when a writer is called without a rendered site model.
	ErrNilSite = errors.New("printingpress: site is required")
)

Functions

func BuildFocusedGraph

func BuildFocusedGraph(allNodes []*v3.Node, allEdges []*v3.Edge, targetNodeID string, maxDepth int) (string, error)

BuildFocusedGraph builds a focused dependency graph around targetNodeID.

It returns explorer JSON, or an empty string when the target has no graph.

func BuildFocusedModelGraph

func BuildFocusedModelGraph(
	allNodes []*v3.Node, allEdges []*v3.Edge, targetNodeID string, maxDepth int, usedByOperations []*OperationRef,
) (string, error)

BuildFocusedModelGraph builds a focused schema graph for a model page.

It includes nearby schema dependencies and any operations that use the model.

func DetectSpecFormat

func DetectSpecFormat(data []byte) string

DetectSpecFormat returns "json" or "yaml" from the first non-whitespace byte.

func PrintJSONArtifacts

func PrintJSONArtifacts(site *ppmodel.Site, outputDir string) error

PrintJSONArtifacts writes the rendered site model to disk as JSON artifacts.

The preferred public entrypoint is bundle.json, which contains the bundled machine-readable site summary and references to the per-page detail files.

When outputDir is empty, PrintJSONArtifacts uses site.OutputDir. A nil site returns ErrNilSite.

func SchemaNodeID

func SchemaNodeID(componentType, name string) string

SchemaNodeID returns the canonical node ID for a component schema.

func WriteHTMLSite

func WriteHTMLSite(site *ppmodel.Site, outputDir, baseURL string) error

WriteHTMLSite writes the full static HTML site to disk.

The site output directory and base URL are taken from the arguments when set, and otherwise fall back to values already stored on the Site.

A nil site returns ErrNilSite.

func WriteLLMSite

func WriteLLMSite(site *Site, outputDir string) error

WriteLLMSite writes LLM-oriented markdown docs to disk.

When outputDir is empty, WriteLLMSite uses site.OutputDir. A nil site returns ErrNilSite.

Types

type ActivitySubscription

type ActivitySubscription struct {
	// contains filtered or unexported fields
}

ActivitySubscription is a best-effort live stream of activity updates.

It is intended for terminal progress display while a job is actively running. Slow consumers may miss intermediate updates and only receive the latest live state. The channel closes when the attached job completes or when the subscription is closed.

func (*ActivitySubscription) Close

func (s *ActivitySubscription) Close()

Close detaches the subscription and closes the update channel.

func (*ActivitySubscription) Drain

func (s *ActivitySubscription) Drain() <-chan ActivityUpdate

Drain detaches the subscription and returns the update channel.

Any already-buffered latest update remains readable before the channel closes.

func (*ActivitySubscription) Unsubscribe

func (s *ActivitySubscription) Unsubscribe()

Unsubscribe detaches the subscription and closes the update channel.

func (*ActivitySubscription) Updates

func (s *ActivitySubscription) Updates() <-chan ActivityUpdate

Updates returns the live activity stream for this subscription.

type ActivityUpdate

type ActivityUpdate struct {
	JobID           string
	JobType         string
	Status          string
	Title           string
	OutputDir       string
	SourceKind      string
	CurrentTask     string
	CompletedTasks  int64
	TotalTasks      int64
	PercentComplete float64
	Elapsed         time.Duration
	TaskDuration    time.Duration
	Error           string
}

ActivityUpdate reports the latest live snapshot of a printing press job.

type AggregatePathOverride added in v0.0.55

type AggregatePathOverride struct {
	Pattern string
	Value   string
}

AggregatePathOverride maps a relative spec path or glob to an explicit value.

type AggregatePressStatistics added in v0.0.55

type AggregatePressStatistics struct {
	BuildMode          string
	Services           int
	Versions           int
	Specs              int
	ChangedSpecs       int
	PoolsUsed          int
	WorkersPerPool     int
	AvailableCores     int
	FilesWritten       int
	BytesWritten       int64
	FileSizes          map[string]int64
	Warnings           []*ppmodel.BuildWarning
	DiscoveryDuration  time.Duration
	GenerationDuration time.Duration
	TotalDuration      time.Duration
}

AggregatePressStatistics reports the outcome of an aggregate print run.

type AggregatePrintingPress added in v0.0.55

type AggregatePrintingPress struct {
	// contains filtered or unexported fields
}

AggregatePrintingPress discovers and renders a multi-spec documentation catalog.

func CreateAggregatePrintingPressFromPath added in v0.0.55

func CreateAggregatePrintingPressFromPath(scanRoot string, config *AggregatePrintingPressConfig) (*AggregatePrintingPress, error)

CreateAggregatePrintingPressFromPath creates a multi-spec printing press rooted at scanRoot.

func (*AggregatePrintingPress) PressModel added in v0.0.55

func (ap *AggregatePrintingPress) PressModel() (*ppmodel.CatalogSite, error)

PressModel discovers specs, groups them into services and versions, and caches the catalog.

func (*AggregatePrintingPress) PrintHTML added in v0.0.55

PrintHTML renders the aggregate catalog and all changed spec sub-sites.

func (*AggregatePrintingPress) PrintJSONArtifacts added in v0.0.55

func (ap *AggregatePrintingPress) PrintJSONArtifacts() (*AggregatePressStatistics, error)

PrintJSONArtifacts writes aggregate JSON metadata and JSON artifacts for all changed spec sub-sites.

func (*AggregatePrintingPress) PrintLLM added in v0.0.55

PrintLLM writes aggregate llms.txt files and per-entry llms output for changed specs.

func (*AggregatePrintingPress) PrintSelectedOutputs added in v0.0.55

func (ap *AggregatePrintingPress) PrintSelectedOutputs(options AggregateRenderOptions) (*AggregatePressStatistics, error)

type AggregatePrintingPressConfig added in v0.0.55

type AggregatePrintingPressConfig struct {
	Title                   string
	Description             string
	ScanRoot                string
	OutputDir               string
	BaseURL                 string
	AssetMode               string
	BuildMode               string
	DisableSkippedRendering bool
	Include                 []string
	IgnoreRules             []string
	NoiseSegments           []string
	ServiceOverrides        []AggregatePathOverride
	DisplayNameOverrides    []AggregatePathOverride
	VersionOverrides        []AggregatePathOverride
	StateNamespace          string
	StateSQLitePath         string
	StateStore              SpecStateStore
	Logger                  *slog.Logger
	MaxPools                int
	WorkersPerPool          int
	Footer                  *ppmodel.FooterConfig
}

AggregatePrintingPressConfig configures repo-tree discovery and multi-spec output.

type AggregateProgressReporter added in v0.0.55

type AggregateProgressReporter interface {
	ReportAggregateProgress(update AggregateProgressUpdate)
}

AggregateProgressReporter receives live aggregate pool progress updates.

type AggregateProgressReporterFunc added in v0.0.55

type AggregateProgressReporterFunc func(update AggregateProgressUpdate)

AggregateProgressReporterFunc adapts a function into an AggregateProgressReporter.

func (AggregateProgressReporterFunc) ReportAggregateProgress added in v0.0.55

func (f AggregateProgressReporterFunc) ReportAggregateProgress(update AggregateProgressUpdate)

ReportAggregateProgress reports an aggregate progress update.

type AggregateProgressUpdate added in v0.0.55

type AggregateProgressUpdate struct {
	Kind           string
	PoolID         int
	PoolLabel      string
	Status         string
	CompletedSpecs int
	TotalSpecs     int
	CompletedBytes int64
	TotalBytes     int64
	CurrentSpec    string
	LastSpec       string
	CurrentStage   string
	CurrentPercent float64
	OverallPercent float64
	Error          string
}

AggregateProgressUpdate describes the latest state of one aggregate render pool.

type AggregateRenderOptions added in v0.0.55

type AggregateRenderOptions struct {
	HTML             bool
	LLM              bool
	JSON             bool
	ProgressReporter AggregateProgressReporter
}

AggregateRenderOptions controls which aggregate outputs are rendered in a single pass.

type ArtifactManifest

type ArtifactManifest struct {
	Format    string              `json:"format"`
	Artifacts []JSONArtifactEntry `json:"artifacts"`
}

ArtifactManifest lists every JSON artifact written by PrintJSONArtifacts.

type CrossRefIndex

type CrossRefIndex struct {
	ComponentToOps       map[string][]*OperationRef // component key → operations using it
	ComponentToComponent map[string][]*ComponentRef // component key → components using it
	ComponentUsesModels  map[string][]*ComponentRef // component key → components it references
}

CrossRefIndex maps components to the operations and components that reference them.

type JSONArtifactEntry

type JSONArtifactEntry struct {
	Kind     string `json:"kind"`
	Path     string `json:"path"`
	Name     string `json:"name,omitempty"`
	Slug     string `json:"slug,omitempty"`
	TypeSlug string `json:"typeSlug,omitempty"`
}

JSONArtifactEntry describes a single emitted JSON artifact.

type JSONBuildWarning

type JSONBuildWarning struct {
	Message string `json:"message"`
	Context string `json:"context,omitempty"`
	Error   string `json:"error,omitempty"`
}

JSONBuildWarning is the serialized warning shape used by bundle.json.

type JSONBundle

type JSONBundle struct {
	Format         string                                  `json:"format"`
	Root           *JSONRootPage                           `json:"root,omitempty"`
	Source         *ppmodel.SourceRef                      `json:"source,omitempty"`
	Nav            []*ppmodel.NavTag                       `json:"nav,omitempty"`
	ModelGroups    []*ppmodel.NavModelGroup                `json:"modelGroups,omitempty"`
	SchemaRegistry map[string]*ppmodel.SchemaRegistryEntry `json:"schemaRegistry,omitempty"`
	Operations     []JSONArtifactEntry                     `json:"operations,omitempty"`
	Models         map[string][]JSONArtifactEntry          `json:"models,omitempty"`
	Webhooks       []JSONArtifactEntry                     `json:"webhooks,omitempty"`
	Warnings       []JSONBuildWarning                      `json:"warnings,omitempty"`
	SpecFormat     string                                  `json:"specFormat,omitempty"`
	Lite           bool                                    `json:"lite,omitempty"`
}

JSONBundle is the top-level public JSON entrypoint written by PrintJSONArtifacts.

type JSONContactInfo

type JSONContactInfo struct {
	Name  string `json:"name,omitempty"`
	URL   string `json:"url,omitempty"`
	Email string `json:"email,omitempty"`
}

JSONContactInfo is the bundle-facing contact shape.

type JSONExternalDocInfo

type JSONExternalDocInfo struct {
	URL         string `json:"url,omitempty"`
	Description string `json:"description,omitempty"`
}

JSONExternalDocInfo is the bundle-facing external documentation shape.

type JSONLicenseInfo

type JSONLicenseInfo struct {
	Name string `json:"name,omitempty"`
	URL  string `json:"url,omitempty"`
}

JSONLicenseInfo is the bundle-facing license shape.

type JSONRootPage

type JSONRootPage struct {
	Title              string                              `json:"title,omitempty"`
	Description        string                              `json:"description,omitempty"`
	DescHTML           string                              `json:"descHtml,omitempty"`
	Version            string                              `json:"version,omitempty"`
	Contact            *JSONContactInfo                    `json:"contact,omitempty"`
	License            *JSONLicenseInfo                    `json:"license,omitempty"`
	Servers            []*JSONServerInfo                   `json:"servers,omitempty"`
	Security           []*ppmodel.SecurityRequirement      `json:"security,omitempty"`
	SecurityGroups     []*ppmodel.SecurityRequirementGroup `json:"securityGroups,omitempty"`
	ExternalDoc        *JSONExternalDocInfo                `json:"externalDoc,omitempty"`
	TagTree            []*ppmodel.NavTag                   `json:"tagTree,omitempty"`
	UntaggedOperations []*ppmodel.NavOperation             `json:"untaggedOperations,omitempty"`
	Webhooks           []*ppmodel.NavOperation             `json:"webhooks,omitempty"`
	Warnings           []JSONBuildWarning                  `json:"warnings,omitempty"`
	Source             *ppmodel.SourceRef                  `json:"source,omitempty"`
}

JSONRootPage is the root page content embedded in bundle.json.

type JSONServerInfo

type JSONServerInfo struct {
	URL         string                    `json:"url,omitempty"`
	Description string                    `json:"description,omitempty"`
	Variables   []*JSONServerVariableInfo `json:"variables,omitempty"`
}

JSONServerInfo is the bundle-facing server shape.

type JSONServerVariableInfo

type JSONServerVariableInfo struct {
	Name        string   `json:"name,omitempty"`
	Default     string   `json:"default,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Description string   `json:"description,omitempty"`
}

JSONServerVariableInfo is the bundle-facing server variable shape.

type ManifestEntry

type ManifestEntry = JSONArtifactEntry

ManifestEntry is kept as a compatibility alias for JSONArtifactEntry.

type MemorySpecStateStore added in v0.0.55

type MemorySpecStateStore struct {
	// contains filtered or unexported fields
}

MemorySpecStateStore is a volatile state store useful for tests and one-shot runs.

func NewMemorySpecStateStore added in v0.0.55

func NewMemorySpecStateStore() *MemorySpecStateStore

NewMemorySpecStateStore creates an in-memory state store.

func (*MemorySpecStateStore) Close added in v0.0.55

func (m *MemorySpecStateStore) Close() error

func (*MemorySpecStateStore) Delete added in v0.0.55

func (m *MemorySpecStateStore) Delete(namespace string, paths []string) error

func (*MemorySpecStateStore) Load added in v0.0.55

func (m *MemorySpecStateStore) Load(namespace string) (map[string]*SpecStateRecord, error)

func (*MemorySpecStateStore) Upsert added in v0.0.55

func (m *MemorySpecStateStore) Upsert(namespace string, records []*SpecStateRecord) error

type PressStatistics

type PressStatistics struct {
	JobID              string
	JobType            string
	Pages              int
	Models             int
	Operations         int
	ClassDiagrams      int
	DependencyGraphs   int
	FilesWritten       int
	BytesWritten       int64
	FileSizes          map[string]int64
	Warnings           []*ppmodel.BuildWarning
	ModelBuildDuration time.Duration
	GenerationDuration time.Duration
	TotalDuration      time.Duration
}

PressStatistics reports the outcome of a single print run, including any non-fatal build warnings carried into the rendered site.

type PrintingPress

type PrintingPress struct {
	// contains filtered or unexported fields
}

PrintingPress generates documentation from an OpenAPI source.

func CreatePrintingPressFromBytes

func CreatePrintingPressFromBytes(specBytes []byte, config *PrintingPressConfig) (*PrintingPress, error)

CreatePrintingPressFromBytes creates a printing press from raw OpenAPI bytes.

BasePath is used to resolve file references when the source spans multiple files. A nil config uses the default options.

func CreatePrintingPressFromDrModel

func CreatePrintingPressFromDrModel(drModel *doctormodel.DrDocument, config *PrintingPressConfig) (*PrintingPress, error)

CreatePrintingPressFromDrModel creates a printing press from an existing doctor model. A nil config uses the default options.

func CreatePrintingPressFromV3Model

func CreatePrintingPressFromV3Model(v3Model *libopenapi.DocumentModel[highv3.Document], config *PrintingPressConfig) (*PrintingPress, error)

CreatePrintingPressFromV3Model creates a printing press from an existing libopenapi v3 model. A nil config uses the default options.

func (*PrintingPress) ActivityStream

func (pp *PrintingPress) ActivityStream() *ActivitySubscription

ActivityStream returns a best-effort live stream of activity snapshots for the current job.

If a job is already running, the latest known snapshot for that job is made available immediately. Subscribers attached to that job are closed automatically after its terminal update is delivered.

The stream is intended for live terminal progress and does not provide durable buffering or replay guarantees. Slow consumers may miss intermediate updates and only receive the most recent live state.

A subscription created after a job has already finished stays idle until the next job starts.

func (*PrintingPress) PressModel

func (pp *PrintingPress) PressModel() (*ppmodel.Site, error)

PressModel builds the in-memory site graph, caches it for later print operations, and returns it without writing any output files.

The returned Site is a cached site instance owned by the PrintingPress. Later calls to PressModel, PrintHTML, and PrintLLM reuse that same value. Mutating the returned Site may leave derived fields out of sync and can produce invalid or incomplete output, so it should be treated as read-only.

func (*PrintingPress) PrintHTML

func (pp *PrintingPress) PrintHTML() (*PressStatistics, error)

PrintHTML writes the HTML site to disk and returns statistics for the run.

It builds the in-memory model first if needed.

func (*PrintingPress) PrintLLM

func (pp *PrintingPress) PrintLLM() (*PressStatistics, error)

PrintLLM writes LLM-oriented documentation files in the llms.txt format to disk and returns statistics for the run.

It builds the in-memory model first if needed.

type PrintingPressConfig

type PrintingPressConfig struct {
	Title         string
	BaseURL       string
	BasePath      string
	SpecPath      string
	SpecURL       string
	OutputDir     string
	AssetMode     string
	DeveloperMode bool
	LintResults   []*v3.RuleFunctionResult
	Footer        *ppmodel.FooterConfig
}

PrintingPressConfig configures how a printing press builds and writes docs.

A nil config is treated as an empty config and uses the default options.

type SiteManifest

type SiteManifest = ArtifactManifest

SiteManifest is kept as a compatibility alias for ArtifactManifest.

type SpecStateRecord added in v0.0.55

type SpecStateRecord struct {
	RelativePath    string
	Hash            string
	ConfigHash      string
	MetadataVersion int
	Title           string
	Summary         string
	ContactName     string
	ContactEmail    string
	ServiceKey      string
	DisplayName     string
	Version         string
	Format          string
	OutputSubdir    string
	UpdatedAt       time.Time
}

SpecStateRecord stores one discovered root spec fingerprint and metadata.

type SpecStateStore added in v0.0.55

type SpecStateStore interface {
	Load(namespace string) (map[string]*SpecStateRecord, error)
	Upsert(namespace string, records []*SpecStateRecord) error
	Delete(namespace string, paths []string) error
	Close() error
}

SpecStateStore persists lightweight discovery/build state between runs.

func NewSQLiteSpecStateStore added in v0.0.55

func NewSQLiteSpecStateStore(dbPath string) (SpecStateStore, error)

NewSQLiteSpecStateStore creates a SQLite-backed persistent state store.

type SyntheticTagFallbackConfig

type SyntheticTagFallbackConfig struct {
	Enabled         bool
	MaxDistinctTags int
	MinOperations   int
}

SyntheticTagFallbackConfig controls when tagged operations should be treated as effectively untagged.

type ValidationError

type ValidationError struct {
	Issues []ValidationIssue
}

ValidationError reports one or more configuration validation problems.

func (*ValidationError) Error

func (v *ValidationError) Error() string

Error returns a compact summary of all validation issues.

func (*ValidationError) Is

func (v *ValidationError) Is(target error) bool

Is reports whether any contained issue matches target.

type ValidationIssue

type ValidationIssue struct {
	Field   string
	Err     error
	Message string
}

ValidationIssue describes one configuration validation problem.

func (ValidationIssue) Error

func (v ValidationIssue) Error() string

Error returns a single-line description of the issue.

Directories

Path Synopsis
cmd
press command
internal
templ: version: v0.3.865
templ: version: v0.3.865

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL