:open_book: `Docs`: The Full Configuration Examples Need to be Added to the Plugin Documentations

[daniel-hutao]

What should be changed?

A long time ago, we had only one configuration file, in a format that probably looked like below:

tools:
  foo: bar

So at that time, the configuration examples given in our plugin documentations are the same as above.

But now the configuration file has been split into 3 parts: core config, var config and tools config. So when a user opens one of our plugin documents and sees the example like below, he won't know how to apply it.

I think all the plugin documentations about the configuration examples should be changed to like below:

---
# core config
varFile: "" # If not empty, use the specified external variables config file
toolFile: "" # If not empty, use the specified external tools config file
state: # state config, backend can be local or s3
  backend: local
  options:
    stateFile: devstream.state

---
# variables config
foo: bar

---
# plugins config
tools:
  - name: foo
    instanceID: default
    options:
      fkk: [[ foo ]]

Please read the documents below.

• [X] I've read the document Creating a Documentation for DevStream and Document Translation(Chinese only). (If you want to submit a document type contribution.)

[daniel-hutao]

@IronCore864 @steinliber @aFlyBird0 @iyear Please leave some comments below.

[steinliber]

If we want to change core config or var config definition, we have to change all docs. I think maybe we can define core, var, and tool config in one docs, And plugin docs only describe it's config items

[iyear]

But it's too redundant, and if our config file changes in the future, every plugin will have to be changed.

It can be explained on the Plugin overview page.

[daniel-hutao]

If we want to change core config or var config definition, we have to change all docs. I think maybe we can define core, var, and tool config in one docs, And plugin docs only describe it's config items

This is a good idea, we add a document to introduce the usage of configuration files, and then in each plugin documentation to declare the current configuration is only "tools config", and tell the users to refer to the documentation we just added for how to write the full configuration files.

cc @iyear

[daniel-hutao]

I'll do it. cc @IronCore864

[IronCore864]

I'll do it. cc @IronCore864

It seems there isn't much progress on this issue for a while. I'll try to finish it today.