docsonnet/doc-util/README.md

package d

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

• fn arg(name, type, default, enums)
• fn fn(help, args)
• fn obj(help, fields)
• fn pkg(name, url, help, filename='', version='master')
• fn render(obj)
• fn val(type, help, default)
• obj argument
  • fn new(name, type, default, enums)
• obj func
  • fn new(help, args)
  • fn withArgs(args)
  • fn withHelp(help)
• obj object
  • fn new(help, fields)
  • fn withFields(fields)
• obj value
  • fn new(type, help, default)
• obj T
• obj package
  • fn new(name, url, help, filename='', version='master')
  • fn newSub(name, help)

Fields

fn arg

arg(name, type, default, enums)

arg is a shorthand for argument.new

fn fn

fn(help, args)

fn is a shorthand for func.new

fn obj

obj(help, fields)

obj is a shorthand for object.new

fn pkg

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

new is a shorthand for package.new

fn render

render(obj)

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)

val is a shorthand for value.new

obj argument

Utilities for creating function arguments

fn argument.new

new(name, type, default, enums)

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

new(help, args)

new creates a new function, optionally with description and arguments

fn func.withArgs

withArgs(args)

The withArgs modifier overrides the arguments of that function

fn func.withHelp

withHelp(help)

The withHelp modifier overrides the help text of that function

obj object

Utilities for documenting Jsonnet objects ({ }).

fn object.new

new(help, fields)

new creates a new object, optionally with description and fields

fn object.withFields

withFields(fields)

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

obj value

Utilities for documenting plain Jsonnet values (primitives)

fn value.new

new(type, help, default)

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

new(name, url, help, filename='', version='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

newSub(name, help)

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

Arguments:

• given name
• help text