feat(docs) prepare api docs generation

[bartsmykla]

Summary

Prerequisites (from repository root path)

cd api
make install/protoc-gen-validate

To mark a file as a file containing policy resource, you should import config.proto and provide option (doc.config) proto extension. For example by adding to file api/mesh/v1alpha1/health_check.proto lines below:

import "config.proto";

option (doc.config) = {
  type: Policy,
  name: "HealthCheck",
  file_name: "health-check"
};

after calling make generate/docs from api there should be generated file health-check.md in the same directory.

Id you want to change the output path for generated files, you can specify a variable called DOCS_OUTPUT_PATH. For example:

DOCS_OUTPUT_PATH=/tmp/kumadocs make generate/docs

it will generate markdown files in /tmp/kumadocs. The path can be absolute or relative

Every markdown file is generated from this template: https://github.com/kumahq/protoc-gen-kumadoc/blob/main/templates/policy.md.tpl and if you would like to test your own templates you should:

1. clone protoc-gen-kumadoc repository

2. make changes in template

3. build plugin: go build . (use -o flag if you want to build the plugin in different output path)

4. run make generate/docs with specified PLUGIN variable:

   PLUGIN=$(pwd)/protoc-gen-kumadoc make generate/docs

More configuration options for proto files can be found here: https://github.com/kumahq/protoc-gen-kumadoc/blob/main/proto/config.proto

1. If you want to mark some field as required (all of them are marked as optional by default), you can use [(doc.required) = true]:

   message BackOff {
     google.protobuf.Duration base_interval = 1 [(doc.required) = true];
     google.protobuf.Duration max_interval = 2;
   }

2. By default all proto "messages" in policy files are being generated as if there would be more than one policy in a file, so if you have more "messages" but only one is considered a real "policy", you can mark rest of them as hidden using option (doc.hide) = true;:

   message Foo {
     option (doc.hide) = true;
     ...
   }
   
   message Retry {
   ...

[nickolaev]

Hmm, why not add the proto file changes in this PR too?

[Bradamant3]

Can't speak to comment from @nickolaev but explanation of tool LGTM. This is awesome, can't wait to work with it when I'm back from time off!