Render Markdown with Jsonnet natively (#26)

Author: Duologic

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test push push-image
+.PHONY: build test push push-image docs
 
 IMAGE_NAME ?= docsonnet
 IMAGE_PREFIX ?= jsonnetlibs
@@ -14,3 +14,7 @@ push: build test push-image
 push-image:
 	docker push $(IMAGE_PREFIX)/$(IMAGE_NAME):$(IMAGE_TAG)
 	docker push $(IMAGE_PREFIX)/$(IMAGE_NAME):latest
+
+docs:
+	jsonnet -J doc-util -S -c -m doc-util/ doc-util/docs.jsonnet
+

doc-util/README.md

@@ -1,23 +1,19 @@
----
-permalink: /
----
-
 # package d
 
 ```jsonnet
-local d = import "github.com/jsonnet-libs/docsonnet/doc-util"
+local d = import 'github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet';
 ```
 
 `doc-util` provides a Jsonnet interface for `docsonnet`,
  a Jsonnet API doc generator that uses structured data instead of comments.
 
-
 ## Index
 
 * [`fn arg(name, type, default)`](#fn-arg)
 * [`fn fn(help, args)`](#fn-fn)
 * [`fn obj(help, fields)`](#fn-obj)
 * [`fn pkg(name, url, help)`](#fn-pkg)
+* [`fn render(obj, filename)`](#fn-render)
 * [`fn val(type, help, default)`](#fn-val)
 * [`obj argument`](#obj-argument)
   * [`fn new(name, type, default)`](#fn-argumentnew)
@@ -28,10 +24,11 @@ local d = import "github.com/jsonnet-libs/docsonnet/doc-util"
 * [`obj object`](#obj-object)
   * [`fn new(help, fields)`](#fn-objectnew)
   * [`fn withFields(fields)`](#fn-objectwithfields)
-* [`obj package`](#obj-package)
-  * [`fn new(name, url, help)`](#fn-packagenew)
 * [`obj value`](#obj-value)
   * [`fn new(type, help, default)`](#fn-valuenew)
+* [`obj T`](#obj-t)
+* [`obj package`](#obj-package)
+  * [`fn new(name, url, help)`](#fn-packagenew)
 
 ## Fields
 
@@ -67,6 +64,24 @@ pkg(name, url, help)
 
 `new` is a shorthand for `package.new`
 
+### fn render
+
+```ts
+render(obj, filename)
+```
+
+`render` converts the docstrings to human readable Markdown files.
+
+Usage:
+
+```jsonnet
+// docs.jsonnet
+d.render(import 'main.libsonnet', 'main.libsonnet')
+```
+
+Call with: `jsonnet -S -c -m docs/ docs.jsonnet`
+
+
 ### fn val
 
 ```ts
@@ -75,86 +90,97 @@ val(type, help, default)
 
 `val` is a shorthand for `value.new`
 
-## obj argument
+### obj argument
 
 Utilities for creating function arguments
 
-### fn argument.new
+#### fn argument.new
 
 ```ts
 new(name, type, default)
 ```
 
 new creates a new function argument, taking the name, the type and optionally a default value
 
-## obj func
+### obj func
 
 Utilities for documenting Jsonnet methods (functions of objects)
 
-### fn func.new
+#### fn func.new
 
 ```ts
 new(help, args)
 ```
 
 new creates a new function, optionally with description and arguments
 
-### fn func.withArgs
+#### fn func.withArgs
 
 ```ts
 withArgs(args)
 ```
 
 The `withArgs` modifier overrides the arguments of that function
 
-### fn func.withHelp
+#### fn func.withHelp
 
 ```ts
 withHelp(help)
 ```
 
 The `withHelp` modifier overrides the help text of that function
 
-## obj object
+### obj object
 
 Utilities for documenting Jsonnet objects (`{ }`).
 
-### fn object.new
+#### fn object.new
 
 ```ts
 new(help, fields)
 ```
 
 new creates a new object, optionally with description and fields
 
-### fn object.withFields
+#### fn object.withFields
 
 ```ts
 withFields(fields)
 ```
 
 The `withFields` modifier overrides the fields property of an already created object
 
-## obj package
-
+### obj value
 
+Utilities for documenting plain Jsonnet values (primitives)
 
-### fn package.new
+#### fn value.new
 
 ```ts
-new(name, url, help)
+new(type, help, default)
 ```
 
-new creates a new package with given `name`, `import` URL and `help` text
+new creates a new object of given type, optionally with description and default value
 
-## obj 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
 
-Utilities for documenting plain Jsonnet values (primitives)
 
-### fn value.new
+#### fn package.new
 
 ```ts
-new(type, help, default)
+new(name, url, help)
 ```
 
-new creates a new object of given type, optionally with description and default value
+new creates a new package with given `name`, `import` URL and `help` text

doc-util/docs.jsonnet

@@ -0,0 +1,3 @@
+local d = import './main.libsonnet';
+
+d.render(import 'main.libsonnet', 'main.libsonnet')

doc-util/main.libsonnet

@@ -73,37 +73,68 @@
   '#arg': self.argument['#new'] + self.func.withHelp('`arg` is a shorthand for `argument.new`'),
   arg:: self.argument.new,
 
-  "#value": d.obj("Utilities for documenting plain Jsonnet values (primitives)"),
+  '#value': d.obj('Utilities for documenting plain Jsonnet values (primitives)'),
   value:: {
-    "#new": d.fn("new creates a new object of given type, optionally with description and default value", [d.arg("type", d.T.string), d.arg("help", d.T.string), d.arg("default", d.T.any)]),
-    new(type, help='', default=null): { 'value': {
+    '#new': d.fn('new creates a new object of given type, optionally with description and default value', [d.arg('type', d.T.string), d.arg('help', d.T.string), d.arg('default', d.T.any)]),
+    new(type, help='', default=null): { value: {
       help: help,
       type: type,
       default: default,
-    } }
+    } },
   },
   '#val': self.value['#new'] + self.func.withHelp('`val` is a shorthand for `value.new`'),
-  val: self.value.new,
+  val:: self.value.new,
 
   // T contains constants for the Jsonnet types
   T:: {
+    '#string': d.val(d.T.string, 'argument of type "string"'),
     string: 'string',
 
+    '#number': d.val(d.T.string, 'argument of type "number"'),
     number: 'number',
     int: self.number,
     integer: self.number,
 
+    '#boolean': d.val(d.T.string, 'argument of type "boolean"'),
     boolean: 'bool',
     bool: self.boolean,
 
+    '#object': d.val(d.T.string, 'argument of type "object"'),
     object: 'object',
+
+    '#array': d.val(d.T.string, 'argument of type "array"'),
     array: 'array',
+
+    '#any': d.val(d.T.string, 'argument of type "any"'),
     any: 'any',
 
-    'null': "null",
-    nil: self["null"],
+    '#null': d.val(d.T.string, 'argument of type "null"'),
+    'null': 'null',
+    nil: self['null'],
 
+    '#func': d.val(d.T.string, 'argument of type "func"'),
     func: 'function',
     'function': self.func,
   },
+
+  '#render': d.fn(
+    |||
+      `render` converts the docstrings to human readable Markdown files.
+
+      Usage:
+
+      ```jsonnet
+      // docs.jsonnet
+      d.render(import 'main.libsonnet', 'main.libsonnet')
+      ```
+
+      Call with: `jsonnet -S -c -m docs/ docs.jsonnet`
+    |||,
+    args=[
+      d.arg('obj', d.T.object),
+      d.arg('filename', d.T.string),
+    ]
+  ),
+  render:: (import './render.libsonnet').render,
+
 }