render

Documentation

Index

• type CellRenderer
• type CellWrapper
• type Config
• type Option
  • func WithCellRenderers(crs ...CellRenderer) Option
• type Pref
  • func (p Pref) Match(cell schema.Cell) bool
• type RenderCellFunc
• type RenderCellFuncRegistry
• type Renderer
  • func NewRenderer(opts ...Option) Renderer

Types

type CellRenderer

type CellRenderer interface {
	// RegisterFuncs registers one or more RenderCellFunc with the passed renderer.
	RegisterFuncs(RenderCellFuncRegistry)
}

CellRenderer registers a RenderCellFunc for every cell type it supports.

Reminiscent of the Visitor pattern, it allows extending the base renderer to support any number of arbitrary cell types.

type CellWrapper

type CellWrapper interface {
	// Wrap the entire cell.
	Wrap(io.Writer, schema.Cell, RenderCellFunc) error

	// WrapInput wraps input block.
	WrapInput(io.Writer, schema.Cell, RenderCellFunc) error

	// WrapOuput wraps output block (code cells).
	WrapOutput(io.Writer, schema.Outputter, RenderCellFunc) error

	// WrapAll wraps all cells in the notebook.
	// This method will be called once and will receive a function
	// to render the rest of the notebook.
	WrapAll(io.Writer, func(io.Writer) error) error
}

CellWrapper renders common wrapping elements for every cell type.

type Config

type Config struct {
	CellWrapper
	CellRenderers []CellRenderer
}

type Option

type Option func(*Config)

func WithCellRenderers

func WithCellRenderers(crs ...CellRenderer) Option

WithCellRenderers adds support for other cell types to the base renderer. If a renderer implements CellWrapper, it will be used to wrap input and output cells. Only one cell wrapper can be configured, and so the last implementor will take precedence.

type Pref

type Pref struct {
	// Type matches cells with the same Type().
	Type schema.CellType

	// MimeType matches cells based on their reported MimeType().
	// Use wildcard syntax (e.g. "image/*" or "*/*") to target
	// wider ranges of cell mime-types.
	MimeType string
}

Pref describes target cell and mime- type.

Preference API is a flexible model which allows multiple CellRenderers to assume responsibility for specific cells. For example:

// Default renderer handles all "display_data" outputs: media, JSON, raw HTML, etc.
reg.Register(render.Pref{Type: schema.DisplayData}, r.renderDisplayData)

// This custom renderer only renders GIFs (regardless of the cell type).
reg.Register(render.Pref{MimeType: "image/gif"}, r.renderGIF)

// Finally, this renderer renders any other image media, but only from "display_data" outputs.
reg.Register(render.Pref{Type: schema.DisplayData, MimeType: "image/*"}, r.renderSQL)

To provide this granularity, registered Prefs are sorted according to their:

1. Specificity: a measure for how precise the selection of target cells is. Simply put, Type < MimeType < (Type+MimeType).
2. Wildcard count: Prefs with less "*" in their MimeType will be prioritized.

func (Pref) Match

func (p Pref) Match(cell schema.Cell) bool

Match checks if the cell matches Pref's criteria.

type RenderCellFunc

type RenderCellFunc func(io.Writer, schema.Cell) error

RenderCellFunc writes contents of a specific cell type.

type RenderCellFuncRegistry

type RenderCellFuncRegistry interface {
	// Register adds a RenderCellFunc and a Pref selector for it.
	Register(Pref, RenderCellFunc)
}

RenderCellFuncRegistry is an interface that extendable Renderers should implement.

type Renderer

type Renderer interface {
	// Render writes the contents of the notebook cells it supports.
	//
	// Implementations should not error on cell types, for which no RenderCellFunc is registered.
	// This is expected, as some [RawCells] will be rendered in some output formats and ignored in others.
	//
	// [RawCells]: https://nbformat.readthedocs.io/en/latest/format_description.html#raw-nbconvert-cells
	Render(io.Writer, schema.Notebook) error

	// AddOptions configures the editor after it has been constructured.
	// The renderer's configuration should not change between renders, and so, implementations should
	// ignore options added after the first call to Render().
	AddOptions(...Option)
}

Renderer renders a decoded notebook in the format it implements.

func NewRenderer

func NewRenderer(opts ...Option) Renderer

NewRenderer extends the base renderer with the passed options.