Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: get arg type information from schema #57

Merged
merged 3 commits into from
Oct 19, 2023
Merged

feat: get arg type information from schema #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b7730dd
feat: get arg type information from schema
Duologic Sep 26, 2023
6dc64c4
fix(render): get type itself from schema
Duologic Sep 26, 2023
4fa63a4
fix: join if type is array regardless
Duologic Sep 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 120 additions & 24 deletions doc-util/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"
* [`fn render(obj)`](#fn-render)
* [`fn val(type, help, default)`](#fn-val)
* [`obj argument`](#obj-argument)
* [`fn fromSchema(name, schema)`](#fn-argumentfromschema)
* [`fn new(name, type, default, enums)`](#fn-argumentnew)
* [`obj func`](#obj-func)
* [`fn new(help, args)`](#fn-funcnew)
Expand All @@ -48,38 +49,65 @@ local d = import "github.com/jsonnet-libs/docsonnet/doc-util/main.libsonnet"
arg(name, type, default, enums)
```

`arg` is a shorthand for `argument.new`
PARAMETERS:

* **name** (`string`)
* **type** (`string`)
* **default** (`any`)
* **enums** (`array`)

`arg` is a shorthand for `argument.new`
### fn fn

```jsonnet
fn(help, args)
```

`fn` is a shorthand for `func.new`
PARAMETERS:

* **help** (`string`)
* **args** (`array`)

`fn` is a shorthand for `func.new`
### fn obj

```jsonnet
obj(help, fields)
```

`obj` is a shorthand for `object.new`
PARAMETERS:

* **help** (`string`)
* **fields** (`object`)

`obj` is a shorthand for `object.new`
### fn pkg

```jsonnet
pkg(name, url, help, filename="", version="master")
```

`new` is a shorthand for `package.new`
PARAMETERS:

* **name** (`string`)
* **url** (`string`)
* **help** (`string`)
* **filename** (`string`)
- default value: `""`
* **version** (`string`)
- default value: `"master"`

`new` is a shorthand for `package.new`
### fn render

```jsonnet
render(obj)
```

PARAMETERS:

* **obj** (`object`)

`render` converts the docstrings to human readable Markdown files.

Usage:
Expand All @@ -91,25 +119,59 @@ d.render(import 'main.libsonnet')

Call with: `jsonnet -S -c -m docs/ docs.jsonnet`


### fn val

```jsonnet
val(type, help, default)
```

`val` is a shorthand for `value.new`
PARAMETERS:

* **type** (`string`)
* **help** (`string`)
* **default** (`any`)

`val` is a shorthand for `value.new`
### obj argument

Utilities for creating function arguments

#### fn argument.fromSchema

```jsonnet
argument.fromSchema(name, schema)
```

PARAMETERS:

* **name** (`string`)
* **schema** (`object`)

`fromSchema` creates a new function argument, taking a JSON `schema` to describe the type information for this argument.

Examples:

```jsonnet
[
d.argument.fromSchema('foo', { type: 'string' }),
d.argument.fromSchema('bar', { type: 'string', default='loo' }),
d.argument.fromSchema('baz', { type: 'number', enum=[1,2,3] }),
]
```

#### fn argument.new

```jsonnet
new(name, type, default, enums)
argument.new(name, type, default, enums)
```

PARAMETERS:

* **name** (`string`)
* **type** (`string`)
* **default** (`any`)
* **enums** (`array`)

`new` creates a new function argument, taking the `name`, the `type`. Optionally it
can take a `default` value and `enum`-erate potential values.

Expand All @@ -123,67 +185,88 @@ Examples:
]
```


### obj func

Utilities for documenting Jsonnet methods (functions of objects)

#### fn func.new

```jsonnet
new(help, args)
func.new(help, args)
```

new creates a new function, optionally with description and arguments
PARAMETERS:

* **help** (`string`)
* **args** (`array`)

new creates a new function, optionally with description and arguments
#### fn func.withArgs

```jsonnet
withArgs(args)
func.withArgs(args)
```

The `withArgs` modifier overrides the arguments of that function
PARAMETERS:

* **args** (`array`)

The `withArgs` modifier overrides the arguments of that function
#### fn func.withHelp

```jsonnet
withHelp(help)
func.withHelp(help)
```

The `withHelp` modifier overrides the help text of that function
PARAMETERS:

* **help** (`string`)

The `withHelp` modifier overrides the help text of that function
### obj object

Utilities for documenting Jsonnet objects (`{ }`).

#### fn object.new

```jsonnet
new(help, fields)
object.new(help, fields)
```

new creates a new object, optionally with description and fields
PARAMETERS:

* **help** (`string`)
* **fields** (`object`)

new creates a new object, optionally with description and fields
#### fn object.withFields

```jsonnet
withFields(fields)
object.withFields(fields)
```

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

* **fields** (`object`)

The `withFields` modifier overrides the fields property of an already created object
### obj value

Utilities for documenting plain Jsonnet values (primitives)

#### fn value.new

```jsonnet
new(type, help, default)
value.new(type, help, default)
```

new creates a new object of given type, optionally with description and default value
PARAMETERS:

* **type** (`string`)
* **help** (`string`)
* **default** (`any`)

new creates a new object of given type, optionally with description and default value
### obj T

* `T.any` (`string`): `"any"` - argument of type "any"
Expand All @@ -201,9 +284,19 @@ new creates a new object of given type, optionally with description and default
#### fn package.new

```jsonnet
new(name, url, help, filename="", version="master")
package.new(name, url, help, filename="", version="master")
```

PARAMETERS:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure I quite understand why PARAMETERS and Arguments are two sections

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good question, I followed the suggestion from this issue: #8

Didn't think it through, I gladly discuss that for a bit, I've seen both words in jsonnet docs, not sure about the context.


* **name** (`string`)
* **url** (`string`)
* **help** (`string`)
* **filename** (`string`)
- default value: `""`
* **version** (`string`)
- default value: `"master"`

`new` creates a new package

Arguments:
Expand All @@ -214,17 +307,20 @@ Arguments:
* `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

```jsonnet
newSub(name, help)
package.newSub(name, help)
```

PARAMETERS:

* **name** (`string`)
* **help** (`string`)

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

Arguments:

* given `name`
* `help` text

20 changes: 20 additions & 0 deletions doc-util/main.libsonnet
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,26 @@
default: default,
enums: enums,
},
'#fromSchema': d.fn(|||
`fromSchema` creates a new function argument, taking a JSON `schema` to describe the type information for this argument.

Examples:

```jsonnet
[
d.argument.fromSchema('foo', { type: 'string' }),
d.argument.fromSchema('bar', { type: 'string', default='loo' }),
d.argument.fromSchema('baz', { type: 'number', enum=[1,2,3] }),
]
```
|||, [
d.arg('name', d.T.string),
d.arg('schema', d.T.object),
]),
fromSchema(name, schema): {
name: name,
schema: schema,
},
},
'#arg': self.argument['#new'] + self.func.withHelp('`arg` is a shorthand for `argument.new`'),
arg:: self.argument.new,
Expand Down
Loading