Documentation
¶
Index ¶
- Constants
- Variables
- func BuildFocusedGraph(allNodes []*v3.Node, allEdges []*v3.Edge, targetNodeID string, maxDepth int) (string, error)
- func BuildFocusedModelGraph(allNodes []*v3.Node, allEdges []*v3.Edge, targetNodeID string, maxDepth int, ...) (string, error)
- func DetectSpecFormat(data []byte) string
- func PrintJSONArtifacts(site *ppmodel.Site, outputDir string) error
- func SchemaNodeID(componentType, name string) string
- func WriteHTMLSite(site *ppmodel.Site, outputDir, baseURL string) error
- func WriteLLMSite(site *Site, outputDir string) error
- type ActivitySubscription
- type ActivityUpdate
- type AggregatePathOverride
- type AggregatePressStatistics
- type AggregatePrintingPress
- func (ap *AggregatePrintingPress) PressModel() (*ppmodel.CatalogSite, error)
- func (ap *AggregatePrintingPress) PrintHTML() (*AggregatePressStatistics, error)
- func (ap *AggregatePrintingPress) PrintJSONArtifacts() (*AggregatePressStatistics, error)
- func (ap *AggregatePrintingPress) PrintLLM() (*AggregatePressStatistics, error)
- func (ap *AggregatePrintingPress) PrintSelectedOutputs(options AggregateRenderOptions) (*AggregatePressStatistics, error)
- type AggregatePrintingPressConfig
- type AggregateProgressReporter
- type AggregateProgressReporterFunc
- type AggregateProgressUpdate
- type AggregateRenderOptions
- type ArtifactManifest
- type CrossRefIndex
- type JSONArtifactEntry
- type JSONBuildWarning
- type JSONBundle
- type JSONContactInfo
- type JSONExternalDocInfo
- type JSONLicenseInfo
- type JSONRootPage
- type JSONServerInfo
- type JSONServerVariableInfo
- type ManifestEntry
- type MemorySpecStateStore
- func (m *MemorySpecStateStore) Close() error
- func (m *MemorySpecStateStore) Delete(namespace string, paths []string) error
- func (m *MemorySpecStateStore) Load(namespace string) (map[string]*SpecStateRecord, error)
- func (m *MemorySpecStateStore) Upsert(namespace string, records []*SpecStateRecord) error
- type PressStatistics
- type PrintingPress
- func CreatePrintingPressFromBytes(specBytes []byte, config *PrintingPressConfig) (*PrintingPress, error)
- func CreatePrintingPressFromDrModel(drModel *doctormodel.DrDocument, config *PrintingPressConfig) (*PrintingPress, error)
- func CreatePrintingPressFromV3Model(v3Model *libopenapi.DocumentModel[highv3.Document], ...) (*PrintingPress, error)
- type PrintingPressConfig
- type SiteManifest
- type SpecStateRecord
- type SpecStateStore
- type SyntheticTagFallbackConfig
- type ValidationError
- type ValidationIssue
Constants ¶
const ( AggregateBuildModeFull = "full" AggregateBuildModeFast = "fast" AggregateBuildModeWatch = "watch" )
const ( AggregateProgressKindPool = "pool" AggregateProgressStatusQueued = "queued" AggregateProgressStatusRunning = "running" AggregateProgressStatusCompleted = "completed" AggregateProgressStatusSkipped = "skipped" )
const ( HTMLAssetModePortable = "portable" HTMLAssetModeServed = "served" )
Variables ¶
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 ¶
DetectSpecFormat returns "json" or "yaml" from the first non-whitespace byte.
func PrintJSONArtifacts ¶
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 ¶
SchemaNodeID returns the canonical node ID for a component schema.
func WriteHTMLSite ¶
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 ¶
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
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
func (ap *AggregatePrintingPress) PrintHTML() (*AggregatePressStatistics, error)
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
func (ap *AggregatePrintingPress) PrintLLM() (*AggregatePressStatistics, error)
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
}
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"`
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
}
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 ¶
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 ¶
ValidationIssue describes one configuration validation problem.
func (ValidationIssue) Error ¶
func (v ValidationIssue) Error() string
Error returns a single-line description of the issue.
Source Files
¶
- activity.go
- agent_writer.go
- aggregate_api.go
- aggregate_discovery.go
- aggregate_render.go
- aggregate_state.go
- aggregate_state_sqlite.go
- aggregate_writer.go
- api.go
- collector.go
- crossref.go
- developer_diagnostics.go
- developer_diagnostics_nav.go
- developer_diagnostics_pages.go
- developer_diagnostics_problems.go
- developer_diagnostics_sources.go
- errors.go
- graph_builder.go
- highlight.go
- html_hydration.go
- html_writer.go
- json_artifacts.go
- markdown.go
- model_crossref_hints.go
- model_layout_hints.go
- press.go
- raw_artifact_cache.go
- schema_artifact_cache.go
- serializer.go
- writer.go