Help us shape the future of Go! Take the 2026 Go Developer Survey

printingpress

package
v0.0.54 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2026 License: Apache-2.0 Imports: 50 Imported by: 0

Documentation

Index

Constants

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 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 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
}

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
press command
templ: version: v0.3.1001
 templ: version: v0.3.1001

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.