Raibid Labs Documentation

README

4 min read

doc-util

doc-util provides a Jsonnet interface for docsonnet, a Jsonnet API doc generator that uses structured data instead of comments.

Install

jb install github.com/jsonnet-libs/docsonnet/doc-util@master

Usage

local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"

Index

Fields

fn arg

arg(name, type, default, enums)

PARAMETERS:

  • name (string)
  • type (string)
  • default (any)
  • enums (array)

arg is a shorthand for argument.new

fn fn

fn(help, args)

PARAMETERS:

  • help (string)
  • args (array)

fn is a shorthand for func.new

fn obj

obj(help, fields)

PARAMETERS:

  • help (string)
  • fields (object)

obj is a shorthand for object.new

fn pkg

pkg(name, url, help, filename="", version="master")

PARAMETERS:

  • name (string)
  • url (string)
  • help (string)
  • filename (string)
    • default value: ""
  • version (string)
    • default value: "master"

new is a shorthand for package.new

fn render

render(obj)

PARAMETERS:

  • obj (object)

render converts the docstrings to human readable Markdown files.

Usage:

// docs.jsonnet
d.render(import 'main.libsonnet')

Call with: jsonnet -S -c -m docs/ docs.jsonnet

fn val

val(type, help, default)

PARAMETERS:

  • type (string)
  • help (string)
  • default (any)

val is a shorthand for value.new

obj argument

Utilities for creating function arguments

fn argument.fromSchema

argument.fromSchema(name, schema)

PARAMETERS:

  • name (string)
  • schema (object)

fromSchema creates a new function argument, taking a JSON schema to describe the type information for this argument.

Examples:

[
  d.argument.fromSchema('foo', { type: 'string' }),
  d.argument.fromSchema('bar', { type: 'string', default='loo' }),
  d.argument.fromSchema('baz', { type: 'number', enum=[1,2,3] }),
]

fn argument.new

argument.new(name, type, default, enums)

PARAMETERS:

  • name (string)
  • type (string)
  • default (any)
  • enums (array)

new creates a new function argument, taking the name, the type. Optionally it can take a default value and enum-erate potential values.

Examples:

[
  d.argument.new('foo', d.T.string),
  d.argument.new('bar', d.T.string, default='loo'),
  d.argument.new('baz', d.T.number, enums=[1,2,3]),
]

obj func

Utilities for documenting Jsonnet methods (functions of objects)

fn func.new

func.new(help, args)

PARAMETERS:

  • help (string)
  • args (array)

new creates a new function, optionally with description and arguments

fn func.withArgs

func.withArgs(args)

PARAMETERS:

  • args (array)

The withArgs modifier overrides the arguments of that function

fn func.withHelp

func.withHelp(help)

PARAMETERS:

  • help (string)

The withHelp modifier overrides the help text of that function

obj object

Utilities for documenting Jsonnet objects ({ }).

fn object.new

object.new(help, fields)

PARAMETERS:

  • help (string)
  • fields (object)

new creates a new object, optionally with description and fields

fn object.withFields

object.withFields(fields)

PARAMETERS:

  • fields (object)

The withFields modifier overrides the fields property of an already created object

obj value

Utilities for documenting plain Jsonnet values (primitives)

fn value.new

value.new(type, help, default)

PARAMETERS:

  • type (string)
  • help (string)
  • default (any)

new creates a new object of given type, optionally with description and default value

obj T

  • T.any (string): "any" - argument of type “any”
  • T.array (string): "array" - argument of type “array”
  • T.boolean (string): "bool" - argument of type “boolean”
  • T.func (string): "function" - argument of type “func”
  • T.null (string): "null" - argument of type “null”
  • T.number (string): "number" - argument of type “number”
  • T.object (string): "object" - argument of type “object”
  • T.string (string): "string" - argument of type “string”

obj package

fn package.new

package.new(name, url, help, filename="", version="master")

PARAMETERS:

  • name (string)
  • url (string)
  • help (string)
  • filename (string)
    • default value: ""
  • version (string)
    • default value: "master"

new creates a new package

Arguments:

  • given name
  • source url for jsonnet-bundler and the import
  • help text
  • filename for the import, defaults to blank for backward compatibility
  • version for jsonnet-bundler install, defaults to master just like jsonnet-bundler

fn package.newSub

package.newSub(name, help)

PARAMETERS:

  • name (string)
  • help (string)

newSub creates a package without the preconfigured install/usage templates.

Arguments:

  • given name
  • help text

Graph View