From 12ae10252941a0fadaeee7e9c0cf5cfe65bdaeef Mon Sep 17 00:00:00 2001 From: "data-plane-api(Azure Pipelines)" Date: Fri, 10 Sep 2021 04:04:51 +0000 Subject: [PATCH] docs: api docs update (#17966) Signed-off-by: Alyssa Wilk Mirrored from https://github.com/envoyproxy/envoy @ ad63b1c385fe95ddd6d547a43583904c1f459abe --- STYLE.md | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/STYLE.md b/STYLE.md index d73e17b7..b185be97 100644 --- a/STYLE.md +++ b/STYLE.md @@ -112,10 +112,9 @@ Extensions must currently be added as v3 APIs following the [package organization](#package-organization) above. To add an extension config to the API, the steps below should be followed: -1. If this is still WiP and subject to breaking changes, use `vNalpha` instead of `vN` in steps - below. Refer to the [Cache filter config](envoy/extensions/filters/http/cache/v3alpha/cache.proto) - as an example of `v3alpha`, and the - [Buffer filter config](envoy/extensions/filters/http/buffer/v3/buffer.proto) as an example of `v3`. +1. If this is still WiP and subject to breaking changes, please tag it + `option (udpa.annotations.file_status).work_in_progress = true;` and + optionally hide it from the docs (`[#not-implemented-hide:]`. 1. Place the v3 extension configuration `.proto` in `api/envoy/extensions`, e.g. `api/envoy/extensions/filters/http/foobar/v3/foobar.proto` together with an initial BUILD file: ```bazel @@ -127,16 +126,26 @@ To add an extension config to the API, the steps below should be followed: deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"], ) ``` -1. Add to the v3 extension config proto `import "udpa/annotations/status.proto";` -1. If this is still WiP and subject to breaking changes, set - `option (udpa.annotations.file_status).work_in_progress = true;`. -1. Add to the v3 extension config proto a file level - `option (udpa.annotations.file_status).package_version_status = ACTIVE;`. +1. Update [source/extensions/extensions_metadata.yaml](../source/extensions/extensions_metadata.yaml) + with the category, security posture, and status. The category field will have to match an + annotation of the form `// [#extension-category: your.extension.category]` + in one of the proto files for the docs build to pass. +1. Update + [source/extensions/extensions_build_config.bzl](source/extensions/extensions_build_config.bzl) + to include the new extension. +1. If the extension is not hidden, find or create a docs file with a toctree + and to reference your proto to make sure users can navigate to it from the API docs + (and to not break the docs build). + See the [key-value-store PR](https://github.com/envoyproxy/envoy/pull/17745/files) for an example of adding a new extension point to common. +1. Make sure your proto imports the v3 extension config proto (`import "udpa/annotations/status.proto";`) +1. Make sure your proto is either tracked as a work in progress + (`option (udpa.annotations.file_status).work_in_progress = true;`) + or ready to be used + (`option (udpa.annotations.file_status).package_version_status = ACTIVE;`). This is required to automatically include the config proto in [api/versioning/BUILD](versioning/BUILD). 1. Add a reference to the v3 extension config in (1) in [api/versioning/BUILD](versioning/BUILD) under `active_protos`. 1. Run `./tools/proto_format/proto_format.sh fix`. This should regenerate the `BUILD` file, - reformat `foobar.proto` as needed and also generate the v4alpha extension config (if needed), - together with shadow API protos. + reformat `foobar.proto` as needed and also generate the shadow API protos. 1. `git add api/ generated_api_shadow/` to add any new files to your Git index. ## API annotations