docs

Documentation

Overview

Package docs renders project documentation (markdown / hugo) from the project config, proto descriptors, and contract.go interfaces.

The behavioural surface is a single Service. Sub-generators (APIGenerator, ArchitectureGenerator, ConfigGenerator, ContractGenerator) implement the package-internal Generator interface and are registered via Registry; that interface is internal scaffolding for the multi-doc pipeline, not the user-facing seam.

Package docs provides automated documentation generation from project metadata. It parses proto definitions, Go AST contracts, and project config to produce markdown or Hugo-compatible documentation.

Code generated by forge. DO NOT EDIT. forge:hash=805624aff8fb05664da0f82d7539b46dce58e5715ac7faec7e9418786bdee023 forge-owned: regenerated every run — do not edit (forge disown to take ownership) Source: contract.go in this package.

To customize: edit contract.go (the interface IS the public surface) and re-run "forge generate". This file is regenerated unconditionally.

Index

• func Run(projectDir string, cfg *config.ProjectConfig, overrides *Overrides) error
• type APIGenerator
  • func (g *APIGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)
  • func (g *APIGenerator) Name() string
• type ArchitectureGenerator
  • func (g *ArchitectureGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)
  • func (g *ArchitectureGenerator) Name() string
• type ConfigGenerator
  • func (g *ConfigGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)
  • func (g *ConfigGenerator) Name() string
• type Context
• type ContractGenerator
  • func (g *ContractGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)
  • func (g *ContractGenerator) Name() string
• type ContractInfo
• type Deps
• type GeneratedDoc
• type Generator
• type MockService
  • func (m *MockService) Run(projectDir string, cfg *config.ProjectConfig, overrides *Overrides) error
• type Overrides
  • func (o *Overrides) Apply(cfg *config.DocsConfig)
• type Registry
  • func DefaultRegistry() *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Get(name string) Generator
  • func (r *Registry) Names() []string
  • func (r *Registry) Register(g Generator)
• type Service
  • func New(d Deps) Service

Functions

func Run

func Run(projectDir string, cfg *config.ProjectConfig, overrides *Overrides) error

Run executes documentation generation for the given project.

Types

type APIGenerator

type APIGenerator struct{}

APIGenerator produces API reference documentation from proto service definitions.

func (*APIGenerator) Generate

func (g *APIGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)

func (*APIGenerator) Name

func (g *APIGenerator) Name() string

type ArchitectureGenerator

type ArchitectureGenerator struct{}

ArchitectureGenerator produces architecture overview documentation with Mermaid diagrams.

func (*ArchitectureGenerator) Generate

func (g *ArchitectureGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)

func (*ArchitectureGenerator) Name

func (g *ArchitectureGenerator) Name() string

type ConfigGenerator

type ConfigGenerator struct{}

ConfigGenerator produces configuration reference documentation from config proto annotations.

func (*ConfigGenerator) Generate

func (g *ConfigGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)

func (*ConfigGenerator) Name

func (g *ConfigGenerator) Name() string

type Context

type Context struct {
	ProjectConfig  *config.ProjectConfig
	Services       []codegen.ServiceDef
	ConfigMessages []codegen.ConfigMessage
	Contracts      []*ContractInfo
	Format         string // "markdown" or "hugo"
	ProjectDir     string
	ModulePath     string
}

Context holds all pre-parsed project data that generators use.

type ContractGenerator

type ContractGenerator struct{}

ContractGenerator produces documentation for internal package contracts.

func (*ContractGenerator) Generate

func (g *ContractGenerator) Generate(ctx *Context) ([]GeneratedDoc, error)

func (*ContractGenerator) Name

func (g *ContractGenerator) Name() string

type ContractInfo

type ContractInfo struct {
	PackageName string
	Contract    *contract.ContractFile
}

ContractInfo holds a parsed contract with its package path.

type Deps

type Deps struct {
	CodegenParser codegen.Parser   // descriptor + go.mod parsing
	Contract      contract.Service // contract.go AST parsing
}

Deps wires the cross-package collaborators docs needs. Each defaults to the canonical implementation when nil.

type GeneratedDoc

type GeneratedDoc struct {
	Path    string // relative path within output dir (e.g. "api/index.md")
	Content []byte
}

GeneratedDoc represents a single generated documentation file.

type Generator

type Generator interface {
	// Name returns the generator's identifier (e.g. "api", "architecture").
	Name() string

	// Generate produces documentation from the given context.
	Generate(ctx *Context) ([]GeneratedDoc, error)
}

Generator produces documentation files from project metadata.

type MockService

type MockService struct {
	contractkit.Recorder
	RunFunc func(string, *config.ProjectConfig, *Overrides) error
}

MockService is a test mock for the Service interface.

The embedded contractkit.Recorder records every call so tests can assert call counts and captured arguments. Set XxxFunc fields to override per-method behaviour; unset methods return the canonical "MockService.<Method>Func not set" error.

func (*MockService) Run

func (m *MockService) Run(projectDir string, cfg *config.ProjectConfig, overrides *Overrides) error

type Overrides

type Overrides struct {
	OutputDir  string
	Format     string
	Generators []string
}

Overrides allows CLI flags to override config values.

func (*Overrides) Apply

func (o *Overrides) Apply(cfg *config.DocsConfig)

Apply merges overrides into the docs config.

type Registry

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

Registry holds named generators that can be selectively enabled.

func DefaultRegistry

func DefaultRegistry() *Registry

DefaultRegistry returns a registry with all built-in generators.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty generator registry.

func (*Registry) Get

func (r *Registry) Get(name string) Generator

Get returns a generator by name, or nil if not found.

func (*Registry) Names

func (r *Registry) Names() []string

Names returns all registered generator names in registration order.

func (*Registry) Register

func (r *Registry) Register(g Generator)

Register adds a generator to the registry.

type Service

type Service interface {
	Run(projectDir string, cfg *config.ProjectConfig, overrides *Overrides) error
}

Service is the docs package's public seam: one entry point that runs the configured generators against a project directory.

func New

func New(d Deps) Service

New constructs a docs.Service. nil Deps fields are filled with the canonical implementation from each collaborator package.