docs: api docs update

CONTRIBUTING.md

@@ -253,15 +253,9 @@ Extension configuration should be located in a directory structure like
 The code for the extension should be located under the equivalent
 `source/extensions/area/plugin`, and include an *envoy_cc_extension* with the
 configuration and tagged with the appropriate security posture, and an
-*envoy_cc_library* with the code. More details on how to add a new extension
-API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api):
+*envoy_cc_library* with the code.
 
-Other changes will likely include
-
-  * Editing [source/extensions/extensions_build_config.bzl](source/extensions/extensions_build_config.bzl) to include the new extensions
-  * Editing [source/extensions/extensions_metadata.yaml](source/extensions/extensions_metadata.yaml) to include metadata for the new extensions
-  * Editing [docs/root/api-v3/config/config.rst](docs/root/api-v3/config/config.rst) to add area/area
-  * Adding `docs/root/api-v3/config/area/area.rst` to add a table of contents for the API docs
+More details on how to add a new extension API can be found [here](api/STYLE.md#adding-an-extension-configuration-to-the-api):
 
 # Adding contrib extensions
 

api/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