refactor: render engine (#53)

* refactor: render engine

* refactor: move install/usage into package.help

* fix: found issues from running this against Grafonnet

- reduce diff as much as possible (mostly whitespace/empty lines)
- ensure relative path for links
- make sure warning message is shown

* chore: render README with new engine

Author: Duologic

doc-util/README.md

@@ -3,7 +3,6 @@
 `doc-util` provides a Jsonnet interface for `docsonnet`,
  a Jsonnet API doc generator that uses structured data instead of comments.
 
-
 ## Install
 
 ```
@@ -16,6 +15,7 @@ jb install github.com/jsonnet-libs/docsonnet/doc-util@master
 local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"
 ```
 
+
 ## Index
 
 * [`fn arg(name, type, default, enums)`](#fn-arg)
@@ -44,39 +44,39 @@ local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"
 
 ### fn arg
 
-```ts
+```jsonnet
 arg(name, type, default, enums)
 ```
 
 `arg` is a shorthand for `argument.new`
 
 ### fn fn
 
-```ts
+```jsonnet
 fn(help, args)
 ```
 
 `fn` is a shorthand for `func.new`
 
 ### fn obj
 
-```ts
+```jsonnet
 obj(help, fields)
 ```
 
 `obj` is a shorthand for `object.new`
 
 ### fn pkg
 
-```ts
+```jsonnet
 pkg(name, url, help, filename="", version="master")
 ```
 
 `new` is a shorthand for `package.new`
 
 ### fn render
 
-```ts
+```jsonnet
 render(obj)
 ```
 
@@ -94,7 +94,7 @@ Call with: `jsonnet -S -c -m docs/ docs.jsonnet`
 
 ### fn val
 
-```ts
+```jsonnet
 val(type, help, default)
 ```
 
@@ -106,7 +106,7 @@ Utilities for creating function arguments
 
 #### fn argument.new
 
-```ts
+```jsonnet
 new(name, type, default, enums)
 ```
 
@@ -130,23 +130,23 @@ Utilities for documenting Jsonnet methods (functions of objects)
 
 #### fn func.new
 
-```ts
+```jsonnet
 new(help, args)
 ```
 
 new creates a new function, optionally with description and arguments
 
 #### fn func.withArgs
 
-```ts
+```jsonnet
 withArgs(args)
 ```
 
 The `withArgs` modifier overrides the arguments of that function
 
 #### fn func.withHelp
 
-```ts
+```jsonnet
 withHelp(help)
 ```
 
@@ -158,15 +158,15 @@ Utilities for documenting Jsonnet objects (`{ }`).
 
 #### fn object.new
 
-```ts
+```jsonnet
 new(help, fields)
 ```
 
 new creates a new object, optionally with description and fields
 
 #### fn object.withFields
 
-```ts
+```jsonnet
 withFields(fields)
 ```
 
@@ -178,15 +178,14 @@ Utilities for documenting plain Jsonnet values (primitives)
 
 #### fn value.new
 
-```ts
+```jsonnet
 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"
@@ -201,7 +200,7 @@ new creates a new object of given type, optionally with description and default
 
 #### fn package.new
 
-```ts
+```jsonnet
 new(name, url, help, filename="", version="master")
 ```
 
@@ -218,7 +217,7 @@ Arguments:
 
 #### fn package.newSub
 
-```ts
+```jsonnet
 newSub(name, help)
 ```
 

doc-util/main.libsonnet

@@ -36,7 +36,10 @@
     new(name, url, help, filename='', version='master')::
       {
         name: name,
-        help: help,
+        help:
+          help
+          + std.get(self, 'installTemplate', '') % self
+          + std.get(self, 'usageTemplate', '') % self,
         'import':
           if filename != ''
           then url + '/' + filename
@@ -70,12 +73,34 @@
         help: help,
       },
 
-    withUsageTemplate(template):: {
-      usageTemplate: template,
+    withInstallTemplate(template):: {
+      installTemplate:
+        if template != null
+        then
+          |||
+
+            ## Install
+
+            ```
+            %s
+            ```
+          ||| % template
+        else '',
     },
 
-    withInstallTemplate(template):: {
-      installTemplate: template,
+    withUsageTemplate(template):: {
+      usageTemplate:
+        if template != null
+        then
+          |||
+
+            ## Usage
+
+            ```jsonnet
+            %s
+            ```
+          ||| % template
+        else '',
     },
   },