Expand documentation with description of sub objects

[luilegeant]

Summary

When reading the documentation, and looking for the manifests specifications, I'm often slowed down to figure out the fields and properties of an object.

I propose to auto-generate any object definitions pages and add links to these pages everytime object is specified as the type in the manifests definitions.

Nice to have:

• When reading a sub-object (see basic example bellow), having a "used by" section with links to all the parents objects referencing the one being read.
• An example of configuration (from an existing test or something equivalent).
• How to set up/use autocomplete, linter, code suggestion tool for the updatecli manifest structure.

Basic example

For this example, I wish to configure the credentials to access a private registry.
I need to configure the auths field when configuring my Dockerfile UpdateCli manifest.

To understand the keywords available and format to use, I need to go and read the updatecli code.

Motivation

The documentation (link provided as an example) states Auths provides a map of registry credentials where the key is the registry URL without scheme. If you're not versed into the language (and its constraints or requirement of the parser used) used for configuration it's hard to understand what/how to do things.

Reduce search time and increase accessibility to the various configuration options.

How to address this issue

Generate documentation page for each configuration object/item.

Link from the keyword type to the generated documentation.

Provide a list of links to places where this "object" is used/applicable.

Provide configuration examples.

[olblak]

You have a valid concern.

The first thing to understand is those documentations, in the table, are coming from the jsonschema generated from the code.
The schema is automatically published on:

• www.updatecli.io/schema/latest/config.json

A long time ago, I wrote some ugly HUGO shortcodes for example:

https://github.com/updatecli/website/blob/master/layouts/shortcodes/resourceparameters

referenced from [here](https://github.com/updatecli/website/blob/778626d23917666069eff1c10c45e350b3d86b11/content/en/docs/plugins/autodiscovery/cargo.adoc?plain=1#L28]

It's using golang templating so it's hard to read/maintain and by far not perfect...

Ideally I would like to replace that shortcode by something easier to maintain but it's quite low in my priorities.

So far the best way to improve the documentation is to update the code comments using markdown syntax.
For example the cargo autodiscovery plugin has more detailed documentation as you can see on https://www.updatecli.io/docs/plugins/autodiscovery/cargo/

with the documentation coming from https://github.com/updatecli/updatecli/blob/main/pkg/plugins/autodiscovery/cargo/main.go

So I think we need to update comment one plugin at a time

[olblak]

I found why some parameter object wouldn't be displayed, I think I fixed it in #2374