DocShell.Presentation.Source behaviour (DocShell v0.3.0)

Copy Markdown View Source

Producer contract for source-independent documentation presentation data.

A producer answers project/1 with a presentation/0, whatever it reads from — authored entries, a knowledge graph, or anything else. The renderer never learns which.

Presentation structs provide a common set of fields and defaults for all producers. Their Jason.Encoder implementations emit the string-keyed JSON contract, including null facets. DocShell.Presentation.GraphProjector validates field types, recursive AST content, and JSON metadata at runtime.

Optional backlinks are available in the in-memory result. The build writes navigation, search, and content artifacts; it does not serialize backlinks.

Summary

Types

presentation()

A renderer-neutral documentation artifact.

Callbacks

project(keyword)

Functions

validate_ids(entries)

Rejects duplicate document IDs, retaining source locations in the error.

Types

presentation()

@type presentation() :: %{
  :schema_version => String.t(),
  :navigation => [DocShell.Presentation.NavigationItem.t()],
  :search => [DocShell.Presentation.SearchEntry.t()],
  :content => %{optional(String.t()) => [DocShell.Ast.ast_node()]},
  optional(:backlinks) => %{
    optional(String.t()) => [DocShell.Presentation.Backlink.t()]
  }
}

A renderer-neutral documentation artifact.

content maps an entry id to its AST nodes; backlinks maps an entry id to the entries that reference it.

Callbacks

project(keyword)

@callback project(keyword()) :: {:ok, presentation()} | {:error, term()}

Functions

validate_ids(entries)

@spec validate_ids([map()]) :: :ok | {:error, term()}

Rejects duplicate document IDs, retaining source locations in the error.