I've started work on this, and the first step was to switch from @envoy_api//docs:protos, which only has the base v2 protos to @envoy_api//:protos, with both v2 and v3 protos, in docs/build.sh. Unsurprisingly, there are a ton of unreferenced v3 RST files in /api-v2/ when run.

This then leads to the question of how we want to structure the API docs in the presence of multiple major versions. Here are some options:

We could have a completely separate doc tree for v2 and v3, with v3 following roughly the same structure as v2 today. The problem with this is that some v3 protos reference v2 protos, since we don't upgrade packages that don't have any breaking changes (and where their transitive deps don't either). So, the v3 tree will either be sparse, with references back to the v2 tree, or dense, containing duplicates of common protos in the v2 tree.
We have a unified API tree, with some section and packages having both v2 and v3 protos side-by-side. The user needs to navigate. This is really confusing.

I'm leaning towards (1) with duplicates. What this would look like is in the v2 API, we might have today:

foo/v2/foo.proto (no breaking changes v2 -> v3)
bar/v2/bar.proto (referencing foo at v2 in the v2 API doctree)

Then v2 tree will continue to look like the above. When you click on the v3 API tab, you would see something like:

foo/v2/foo.proto
bar/v3/bar.proto (referencing foo at v2 in the v3 API doctree)

@mattklein123 @lizan WDYT?

v3 API docs #8087

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions