chore(external docs): render array of object type in component docs

[titaneric]

Summary

Try to resolve #22136.

log_to_metric transforms

static metric

Change Type

• Bug fix
• New feature
• Non-functional (chore, refactoring, docs)
• Performance

Is this a breaking change?

• Yes
• No

How did you test this PR?

make quick-build
make serve

Navigate to log to metric transforms and static metric

Does this PR include user facing changes?

• Yes. Please add a changelog fragment based on our guidelines.
• No. A maintainer will apply the "no-changelog" label to this PR.

Checklist

• Please read our Vector contributor resources.
• If this PR introduces changes Vector dependencies (modifies Cargo.lock), please
  run dd-rust-license-tool write to regenerate the license inventory and commit the changes (if any). More details here.

References

Close #22136

[titaneric]

I have to admit that I am neither a frontend engineer nor a UI expert, but I have added some margin same as array's example, and I need some time to compare the implementation between mine and data model rendering.

[pront]

I have to admit that I am neither a frontend engineer nor a UI expert, but I have added some margin same as array's example, and I need some time to compare the implementation between mine and data model rendering.

I appreciate your efforts on this. I am also not an expert with frontend stuff. If it helps, this is how I test Vector website locally:

cd /path/to/vector/root
# make generate-component-docs # needed only if you modify configurable components in Rust
cd website
make run-production-site-locally

Need to install Hugo e.g. brew install hugo for the above to work.

[titaneric]

Added some margin on top of config object

Decrease the margin on top of array example and make it consistent to padding of outer container.

Now the doc looks right enough, but I am welcome to here more suggestions.

[pront]

Thank you this is a great improvement.

I noticed in one of your screenshots this grey bubble:
. I wonder if that is also a rendering bug.

[titaneric]

Node that Line 119 (rendering config object) has the similar margin.

[titaneric]

Let me take a look at the grey bubble

[titaneric]

It takes charge to render the v.syntax such as template, regex, string and so on. But there is no syntax defined in metric field in log_to_metric transforms, so it just render an empty bubble here. Perhaps we could conditionally render the gray bubble when there is syntax field defined?

[titaneric]

A more serious issue encountered. I want to add syntax field to preview the rendering result:

	metrics: {
		description: "A list of metrics to generate."
		required:    true
		type: array: items: type: object {
			examples: [
				{
					field: "value_transform_total"
					counter: {
						value: 10.0
					}
					kind: "incremental"
					name: "test.transform.counter"
					tags: {
						env:  "test_env"
						host: "localhost"
					}
				},
			]
			syntax: "template"

but I have the following error:

components.transforms.log_to_metric.configuration.metrics.type.array.items.type.object.syntax: field not allowed

It seems that it does not fit the current schema? Perhaps deleting the gray bubble is another solution.

---

Updated:

Okay, now I fully understand how the schema in cue works in vector, there is no syntax field defined in TypeArray, so it breaks the syntax when I want to add syntax field in metric type.

[pront]

LGTM

How does this look to you? cc @jszwedko

[jszwedko]

Nice work on this @titaneric . This issue has been a pet peeve for me for a long while but I was never able to muster the energy to dig into it. The rendering looks good to me. I would like to see if we could drop that extra grey syntax oval if possible.

[titaneric]

Thank you, I think if syntax is not necessary for the array type and we could simply delete it since it's not defined in the array's schema.

[pront]

Thank you, I think if syntax is not necessary for the array type and we could simply delete it since it's not defined in the array's schema.

As you pointed it out, syntax isn't defined there. If you have a few minutes you could just define it (like so) and see how it renders, if the result is not good, let's just delete it 👍

[titaneric]

I have deleted it! Hope that the preview website could be successfully deployed.

[pront]

Great improvement:

Tangential: Hmm the website wasn't generated even the though there's website in the branch name. Maybe it doesn't work on fork brances. cc @devindford

[jszwedko]

Awesome, thanks for this fix @titaneric !

[jszwedko]

Actually, I'm sorry, I think this isn't quite right. This removes the syntax for arrays of elements that do have syntax.

For example, group_by for reduce:

Before this change:

After this change:

Notice literal is removed.

[titaneric]

Thank you for pointing out this one. I am wondering why array type could have syntax field. Let me dig into it.

[titaneric]

Ok, I find there is a syntax filed defined in string, and it would render the syntax on the page since the group_by is the array of string. Let me fix it.

[titaneric]

I conditionally render the page if the $v.syntax is defined.

reduce page:

log_to_metric page:

[jszwedko]

Awesome, thanks @titaneric ! This looks good to me now (both the reduce and log_to_metric transform pages).