mirror of
https://github.com/TECHNOFAB11/docsonnet.git
synced 2026-02-02 07:35:11 +01:00
feat: inline package declaration
Docsonnet packages previously used to be declared in a `main.docsonnet`. Because this file basically always contains the same, it is kinda redundant. To avoid that, the information from there has been inlined into the main Jsonnet file, while the parser logic will become part of the Go application, as embedded Jsonnet.
This commit is contained in:
sh0rez
parent
a63ddd1061
commit
5fbee517fe
4 changed files with 91 additions and 83 deletions
|
|
@ -1,8 +1 @@
|
|||
local d = import './main.libsonnet';
|
||||
|
||||
d.new('d', url='github.com/jsonnet-libs/docsonnet/doc-util')
|
||||
+ d.withAPI(import './main.libsonnet')
|
||||
+ d.withHelp(|||
|
||||
`doc-util` provides a Jsonnet interface for `docsonnet`,
|
||||
a Jsonnet API doc generator that uses structured data instead of comments.
|
||||
|||)
|
||||
(import "../load.libsonnet").package(import "./main.libsonnet")
|
||||
|
|
|
|||
|
|
@ -1,114 +1,71 @@
|
|||
local _internal = {
|
||||
// clean removes the hash from the key
|
||||
clean(str): std.strReplace(str, '#', ''),
|
||||
|
||||
include(api, key):
|
||||
// include docsonnet fields
|
||||
if std.startsWith(key, '#') then true
|
||||
|
||||
// non-docsonnet object, might have nested docsonnet
|
||||
else if std.isObject(api[key]) then
|
||||
// skip if has docsonnet counterpart
|
||||
(if std.objectHasAll(api, '#' + key) then false else true)
|
||||
|
||||
// some other field, skip it
|
||||
else false,
|
||||
|
||||
// ds deals with docsonnet fields. Also checks for nested objects for
|
||||
//docsonnet ones
|
||||
ds(api, key):
|
||||
local cleaned = self.clean(key);
|
||||
if std.objectHasAll(api[key], 'object') && std.objectHasAll(api, cleaned) then
|
||||
api[key] + $.object.withFields($.filter(api[cleaned]))
|
||||
else
|
||||
api[key],
|
||||
|
||||
// filter returns only docsonnet related objects from the api
|
||||
filter(api): {
|
||||
[self.clean(key)]:
|
||||
// include all docsonnet
|
||||
if std.startsWith(key, '#') then
|
||||
$.ds(api, key)
|
||||
// create docsonnet objects from regular ones
|
||||
else if std.isObject(api[key]) then
|
||||
$.obj('', $.filter(api[key]))
|
||||
|
||||
for key in std.objectFields(api)
|
||||
if self.include(api, key)
|
||||
},
|
||||
|
||||
fromMain(main): self.filter(main),
|
||||
};
|
||||
|
||||
{
|
||||
local internal = self + _internal,
|
||||
local d = self,
|
||||
|
||||
'#new': d.fn('`new` initiates the api documentation model, taking the `name` and import `url` of your project', [d.arg('name', d.T.string), d.arg('url', d.T.string)]),
|
||||
new(name, url):: {
|
||||
name: name,
|
||||
'import': url,
|
||||
'#': d.pkg(
|
||||
name='d',
|
||||
url='github.com/sh0rez/docsonnet/doc-util',
|
||||
help=|||
|
||||
`doc-util` provides a Jsonnet interface for `docsonnet`,
|
||||
a Jsonnet API doc generator that uses structured data instead of comments.
|
||||
|||
|
||||
),
|
||||
|
||||
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,
|
||||
},
|
||||
},
|
||||
|
||||
'#withAPI': d.fn('`withAPI` automatically builds the docsonnet model from your public API. The `main` parameter is usually set to `import "./main.libsonnet"`.', [d.arg('main', d.T.object)]),
|
||||
withAPI(main):: {
|
||||
api: internal.fromMain(main),
|
||||
},
|
||||
'#pkg':: self.package['#new'] + d.func.withHelp('`new` is a shorthand for `package.new`'),
|
||||
pkg:: self.package.new,
|
||||
|
||||
'#withFields': d.fn('`withFields` allows to manually specify the docsonnet model. Usually `withAPI` is the better alternative', [d.arg('fields', d.T.object)]),
|
||||
withFields(fields):: {
|
||||
api: fields,
|
||||
},
|
||||
|
||||
"#withHelp": d.fn("`withHelp` sets the main description text, displayed right under the package's name", [d.arg("help", d.T.string)]),
|
||||
withHelp(help):: {
|
||||
help: help,
|
||||
},
|
||||
|
||||
"#object": d.obj("Utilities for documenting Jsonnet objects (`{ }`)."),
|
||||
'#object': d.obj('Utilities for documenting Jsonnet objects (`{ }`).'),
|
||||
object:: {
|
||||
"#new": d.fn("new creates a new object, optionally with description and fields", [d.arg("help", d.T.string), d.arg("fields", d.T.object)]),
|
||||
'#new': d.fn('new creates a new object, optionally with description and fields', [d.arg('help', d.T.string), d.arg('fields', d.T.object)]),
|
||||
new(help='', fields={}):: { object: {
|
||||
help: help,
|
||||
fields: fields,
|
||||
} },
|
||||
|
||||
"#withFields": d.fn("The `withFields` modifier overrides the fields property of an already created object", [d.arg("fields", d.T.object)]),
|
||||
'#withFields': d.fn('The `withFields` modifier overrides the fields property of an already created object', [d.arg('fields', d.T.object)]),
|
||||
withFields(fields):: { object+: {
|
||||
fields: fields,
|
||||
} },
|
||||
},
|
||||
|
||||
"#obj": self.object["#new"] + d.func.withHelp("`obj` is a shorthand for `object.new`"),
|
||||
'#obj': self.object['#new'] + d.func.withHelp('`obj` is a shorthand for `object.new`'),
|
||||
obj:: self.object.new,
|
||||
|
||||
"#func": d.obj("Utilities for documenting Jsonnet methods (functions of objects)"),
|
||||
'#func': d.obj('Utilities for documenting Jsonnet methods (functions of objects)'),
|
||||
func:: {
|
||||
"#new": d.fn("new creates a new function, optionally with description and arguments", [d.arg("help", d.T.string), d.arg("args", d.T.array)]),
|
||||
'#new': d.fn('new creates a new function, optionally with description and arguments', [d.arg('help', d.T.string), d.arg('args', d.T.array)]),
|
||||
new(help='', args=[]):: { 'function': {
|
||||
help: help,
|
||||
args: args,
|
||||
} },
|
||||
|
||||
"#withHelp": d.fn("The `withHelp` modifier overrides the help text of that function", [d.arg("help", d.T.string)]),
|
||||
withHelp(help):: {'function'+: {
|
||||
'#withHelp': d.fn('The `withHelp` modifier overrides the help text of that function', [d.arg('help', d.T.string)]),
|
||||
withHelp(help):: { 'function'+: {
|
||||
help: help,
|
||||
}}
|
||||
} },
|
||||
},
|
||||
|
||||
"#fn": self.func["#new"] + d.func.withHelp("`fn` is a shorthand for `func.new`"),
|
||||
'#fn': self.func['#new'] + d.func.withHelp('`fn` is a shorthand for `func.new`'),
|
||||
fn:: self.func.new,
|
||||
|
||||
"#argument": d.obj("Utilities for creating function arguments"),
|
||||
'#argument': d.obj('Utilities for creating function arguments'),
|
||||
argument:: {
|
||||
"#new": d.fn("new creates a new function argument, taking the name, the type and optionally a default value", [d.arg("name", d.T.string), d.arg("type", d.T.string), d.arg("default", d.T.any)]),
|
||||
'#new': d.fn('new creates a new function argument, taking the name, the type and optionally a default value', [d.arg('name', d.T.string), d.arg('type', d.T.string), d.arg('default', d.T.any)]),
|
||||
new(name, type, default=null): {
|
||||
name: name,
|
||||
type: type,
|
||||
default: default,
|
||||
},
|
||||
},
|
||||
"#arg": self.argument["#new"] + self.func.withHelp("`arg` is a shorthand for `argument.new`"),
|
||||
'#arg': self.argument['#new'] + self.func.withHelp('`arg` is a shorthand for `argument.new`'),
|
||||
arg:: self.argument.new,
|
||||
|
||||
// T contains constants for the Jsonnet types
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue