Extend render template with common usage & install instructions (#27)

* Extend render template with jsonnet-bundler instructions * push usage/install templates up the stack * ensure newline between docs and header * correctly quote default args
jsonnet-libs · Jun 13, 2022 · fedfb49 · fedfb49
1 parent f47f46f
commit fedfb49
Show file tree

Hide file tree

Showing 5 changed files with 119 additions and 34 deletions.
diff --git a/Makefile b/Makefile
@@ -16,5 +16,6 @@ push-image:
 	docker push $(IMAGE_PREFIX)/$(IMAGE_NAME):latest
 
 docs:
-	jsonnet -J doc-util -S -c -m doc-util/ doc-util/docs.jsonnet
+	jsonnet -S -c -m doc-util/ \
+		-e "(import 'doc-util/main.libsonnet').render(import 'doc-util/main.libsonnet')"
 
diff --git a/doc-util/README.md b/doc-util/README.md
@@ -1,19 +1,28 @@
 # package d
 
-```jsonnet
-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.
 
+
+## Install
+
+```
+jb install github.com/jsonnet-libs/docsonnet/doc-util@master
+```
+
+## Usage
+
+```jsonnet
+local d = import "github.com/jsonnet-libs/docsonnet/doc-util/doc-util/main.libsonnet"
+```
+
 ## 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 pkg(name, url, help, filename='', version='master')`](#fn-pkg)
+* [`fn render(obj)`](#fn-render)
 * [`fn val(type, help, default)`](#fn-val)
 * [`obj argument`](#obj-argument)
   * [`fn new(name, type, default)`](#fn-argumentnew)
@@ -28,7 +37,7 @@ local d = import 'github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet';
   * [`fn new(type, help, default)`](#fn-valuenew)
 * [`obj T`](#obj-t)
 * [`obj package`](#obj-package)
-  * [`fn new(name, url, help)`](#fn-packagenew)
+  * [`fn new(name, url, help, filename='', version='master')`](#fn-packagenew)
 
 ## Fields
 
@@ -59,15 +68,15 @@ obj(help, fields)
 ### fn pkg
 
 ```ts
-pkg(name, url, help)
+pkg(name, url, help, filename='', version='master')
 ```
 
 `new` is a shorthand for `package.new`
 
 ### fn render
 
 ```ts
-render(obj, filename)
+render(obj)
 ```
 
 `render` converts the docstrings to human readable Markdown files.
@@ -76,7 +85,7 @@ Usage:
 
 ```jsonnet
 // docs.jsonnet
-d.render(import 'main.libsonnet', 'main.libsonnet')
+d.render(import 'main.libsonnet')
 ```
 
 Call with: `jsonnet -S -c -m docs/ docs.jsonnet`
@@ -180,7 +189,16 @@ new creates a new object of given type, optionally with description and default
 #### fn package.new
 
 ```ts
-new(name, url, help)
+new(name, url, help, filename='', version='master')
 ```
 
-new creates a new package with given `name`, `import` URL and `help` text
+`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
+
diff --git a/doc-util/docs.jsonnet b/doc-util/docs.jsonnet
diff --git a/doc-util/main.libsonnet b/doc-util/main.libsonnet
@@ -7,15 +7,54 @@
     help=|||
       `doc-util` provides a Jsonnet interface for `docsonnet`,
        a Jsonnet API doc generator that uses structured data instead of comments.
-    |||
+    |||,
+    filename=std.thisFile,
   ),
 
   package:: {
-    '#new':: d.fn('new creates a new package with given `name`, `import` URL and `help` text', [d.arg('name', d.T.string), d.arg('url', d.T.string), d.arg('help', d.T.string)]),
-    new(name, url, help):: {
-      name: name,
-      'import': url,
-      help: help,
+    '#new':: d.fn(|||
+      `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
+    |||, [
+      d.arg('name', d.T.string),
+      d.arg('url', d.T.string),
+      d.arg('help', d.T.string),
+      d.arg('filename', d.T.string, ''),
+      d.arg('version', d.T.string, 'master'),
+    ]),
+    new(name, url, help, filename='', version='master')::
+      {
+        name: name,
+        help: help,
+        'import':
+          if filename != ''
+          then url + '/' + filename
+          else url,
+        url: url,
+        filename: filename,
+        version: version,
+
+      }
+      + self.withInstallTemplate(
+        'jb install %(url)s@%(version)s'
+      )
+      + self.withUsageTemplate(
+        'local %(name)s = import "%(import)s"'
+      ),
+
+    withUsageTemplate(template):: {
+      usageTemplate: template,
+    },
+
+    withInstallTemplate(template):: {
+      installTemplate: template,
     },
   },
 
@@ -125,14 +164,13 @@
 
       ```jsonnet
       // docs.jsonnet
-      d.render(import 'main.libsonnet', 'main.libsonnet')
+      d.render(import '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,

diff --git a/doc-util/render.libsonnet b/doc-util/render.libsonnet
@@ -5,11 +5,7 @@
     package: |||
       # package %(name)s
 
-      ```jsonnet
-      local %(name)s = import '%(import)s/%(filename)s';
-      ```
-
-      %(help)s
+      %(content)s
     |||,
 
     indexPage: |||
@@ -186,7 +182,11 @@
 
       args: std.join(', ', [
         if arg.default != null
-        then arg.name + '=' + arg.default
+        then arg.name + '=' + (
+          if arg.type == 'string'
+          then "'%s'" % arg.default
+          else std.toString(arg.default)
+        )
         else arg.name
         for arg in self.doc.args
       ]),
@@ -203,15 +203,46 @@
       help: doc.value.help,
       value: obj,
     },
+
+    package(doc, root):: {
+      name: doc.name,
+      content:
+        |||
+          %(help)s
+        ||| % doc
+        + (if 'installTemplate' in doc
+           then |||
+
+             ## Install
+
+             ```
+             %(install)s
+             ```
+           ||| % doc.installTemplate % doc
+           else '')
+        + (if 'usageTemplate' in doc
+           then |||
+
+             ## Usage
+
+             ```jsonnet
+             %(usage)s
+             ```
+           ||| % doc.usageTemplate % doc
+           else ''),
+    },
   },
 
-  prepare(obj, filename='', depth=0)::
+  prepare(obj, depth=0)::
     std.foldl(
       function(acc, key)
         acc +
         // Package definition
         if key == '#'
-        then obj[key] { filename: filename }
+        then root.sections.package(
+          obj[key],
+          (depth == 0)
+        )
 
         // Field definition
         else if std.startsWith(key, '#')
@@ -319,6 +350,6 @@
       {}
     ),
 
-  render(obj, filename):
-    self.renderFiles(self.prepare(obj, filename)),
+  render(obj):
+    self.renderFiles(self.prepare(obj)),
 }