<!-- The following is generated by cargo-rdme from lib.rs, and should not be modified manually-->
<!-- cargo-rdme start -->

# Fiberplane Templates

> Programmatically generate Fiberplane Notebooks for repeatable workflows

## Overview

Fiberplane Templates are built with the [Jsonnet](https://jsonnet.org/) data
templating language.

This crate includes:

- Fiberplane [Jsonnet library](./fiberplane.libsonnet) with functions for
  creating notebooks
  ([API Docs](https://docs.fiberplane.com/reference/templates-api))
- Rust library for expanding templates into notebooks and for converting
  existing notebooks into templates

## Quickstart

The [Fiberplane CLI](https://github.com/fiberplane/fp) is the recommended way to
interact with Templates (see the
[docs](https://docs.fiberplane.com/docs/working-with-templates) or run
`fp help templates`).

## Structure of a Template

Most Fiberplane Templates export a Jsonnet function that accepts some parameters
and creates a notebook using the helper functions provided by the Fiberplane
Jsonnet library.

```jsonnet
local fp = import 'fiberplane.libsonnet';
local c = fp.cell;
local fmt = fp.format;

// Parameters are named and can have default values
function(incidentName='API Outage')
  fp.notebook
    .new('Incident Response for: ' + incidentName)
    .setTimeRangeRelative(minutes=60)
    .addCells([
      // The library exposes helper functions for creating every cell type
      c.h1('Heading'),
      c.text(
        // There are also helper functions for formatting text
        fmt.bold('Hello World!')
      )
    ])
```

See the [templates repo](https://github.com/fiberplane/templates) for more
detailed, use-case-specific templates.

## Snippets

Snippets are smaller pieces of Jsonnet code that produce reusable arrays of
notebook cells, rather than whole notebooks.

```jsonnet
local fp = import 'fiberplane.libsonnet';
local c = fp.cell;
local fmt = fp.format;

fp.snippet([
  c.h2('I am a snippet'),
  c.code('Here is some code'),
])
```

<!-- cargo-rdme end -->

## Example Templates

There are [example templates](https://github.com/fiberplane/templates) for
various use cases such as incident response, root cause analysis, etc.

## Template API Documentation

See the [generated API docs](https://docs.fiberplane.com/reference/templates-api).

## Development

### VS Code

If you want to edit Jsonnet files in VS Code, you can use the
[Jsonnet NG](https://marketplace.visualstudio.com/items?itemName=Sebbia.jsonnetng)
extension.

You should add the following to your VS Code `settings.json` file to edit
template files without it showing errors. This includes the Fiberplane Jsonnet
library and external variables normally provided by the template expansion
functions.

```json
{
  "jsonnet.libPaths": ["path/to/fiberplane/templates/"]
}
```

### Running Tests

To run the tests (including the examples), run:

```shell
cargo test --lib --examples
```

### Generating Documentation

The Jsonnet library API documentation is generated from
[JSDoc](https://jsdoc.app/) comments in
[fiberplane.libsonnet](./fiberplane.libsonnet) using
[jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).

To (re)generate the documentation, you can use this Docker command:

```shell
docker run --rm -v $PWD:$PWD node:17 npx -y jsdoc-to-markdown -c $PWD/jsdoc.json $PWD/fiberplane.libsonnet > docs/template_api.md
```

Alternatively, you can use Node.js directly by using the following command:

```shell
npx -y jsdoc-to-markdown -c jsdoc.json fiberplane.libsonnet > docs/template_api.md
```
