It is useful to support constants in libraries like (in fact doc-utils does this)

{  
   colors: {
     '#green': d.const("the color green")
     green: "green"
   }
}

As such, I'd like to be able to document these constants. Possible look for this:

Constants

• colors.green (string) : "green" - the color green

Testing using the docker master image, but I believe the pkger.go code is using old jsonnet files that don't have the "filename" and "version" parameters in the d.pkg() function.

Given that the most recent changes appear to allow rendering the docs directly using jsonnet, is the recommended path forward to directly use: jsonnet -S -c -m docs/ docs.jsonnet instead of the docsonnet binary?

Hello!

I ran into a problem the std.manifestYamlDoc function does not have a quote_keys parameter

Apparently because the project uses an older version of jsonnet 0.15

Are there any restrictions for upgrading to jsonnet 0.18?

Below is an example of how I discovered the issue:

  '#new'+: d.fn(
    help=
    |||
      Some function

      Optional arguments can be passed as an array of `args`

      ```yaml
      %(defaults)s
      ```
    ||| % { defaults: std.manifestYamlDoc({args: defaults}, quote_keys=false) },
    args=[
      d.arg('name', d.T.string),
      d.arg('args', d.T.array, {}),
    ]
  ),
  new(name=error 'Application name is unset', args={})::

docsonnet -o docs/ main.libsonnet

Extracting: RUNTIME ERROR: function has no parameter quote_keys

Also I tried using docsonnet versions:

• v0.0.4-0.20220713111504-be066653f33f
• v0.0.3

Both docsonnet documentation fields below are rendered similarly such that I imagine a user could easily be confused by the structure of the data when seeing the Markdown documentation for a key with periods . in it.

{
  '#has.a.period': d.val('help'),
  'has.a.period': null,
  has: {
    a: {
      '#period': d.val('help'),
      period: null,
    },
  },
}

I guess keys that require quoting in Jsonnet should be enclosed in square brackets, the same as in Jsonnet so that the first key becomes ['has.a.period'] in the rendered documentation and the second key stays as has.a.period.

I think it would be helpful to allow each parameter, and return value to be explained. Additionally, whether or not an error or assertion could be raised (outside of the usual suspects)

Reference

https://pillow.readthedocs.io/en/stable/reference/Image.html#functions

fn pkg.something

something(o, x)

something does some stuff

PARAMETERS

• o (object) - an object
• x (any) - an array or string for blah

RETURNS

object - a fizzbuzz

ASSERTIONS

• If o or x are null

### fn pkg.something

```ts
something(o, x)
```

`something` does some stuff

> `PARAMETERS`

* `o (object)` - an object
* `x (any)` - an array or string for blah

> `RETURNS`

`object` - a fizzbuzz

> `ASSERTIONS`

* If `o` or `x` are null

might be useful to suggest to use ||| syntax for readability of the description.

{
  '#array': d.fn(
    |||
      `array` takes a single argument of any type.
      If it is an array, it returns it, otherwise it is wrapped in an array.
    |||,
    [d.arg('x', d.T.any)]),
  array(x):: (if std.type(x) == "array" then x else [x]),
}

since jsonnet doesn't use fn or obj, I think it would enhance readability by spelling those out.

Current (with backticks, see #5)

obj container
fn container.keyValuePairs

Suggested

object container
function container.keyValuePairs

Similar to this:
https://golang.org/pkg/encoding/json/#HTMLEscape

Example

<details>
<summary>Example</summary>

```jsonnet
this is an example
```
</details>

Hi,

Would you be able to confirm whether this is expected to work?

I find that any object/function under new() does not get picked up by docsonnet , i.e. there's no inside_object - was hoping it would also get rendered into markdown :)

local d = import 'doc-util/main.libsonnet';
{
  // package declaration
  '#': d.pkg(
    name='myapp',
    url='...',
    help='`myapp` implements a ...',
  ),

  '#outside_object': d.obj('This works and docsonnet renders it'),
  outside_object+:: {
    foo: {},
  },

  '#new':: d.fn(help='new returns an instance of myapp',
                args=[
                  d.arg(name='config', type=d.T.string),
                  d.arg(name='name', type=d.T.string),
                ]),

  new(config, name)::
    {
      '#inside_object': d.obj('This does not get rendered by docsonnet'),
      inside_object+:: {
        foo: {},
      },
    },
}

renders to

permalink: /

package myapp

local myapp = import "..."

myapp implements a ...

Index

• fn new(config, name)
• obj outside_object

Fields

fn new

new(config, name)

new returns an instance of myapp

obj outside_object

This works and docsonnet renders it

This is an issue to talk about the issues involved in a desugared implementation.

AFAIK, the main issue is about the AST not providing access to comments?

current:

fn container.array

### fn container.array

suggested:

fn container.array

### fn `container.array`

I noticed that this doesn't work:

local d = import "github.com/sh0rez/docsonnet/doc-util";

but this does:

local d = import 'doc-util/main.libsonnet';