Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

v3 API docs #8087

Closed
htuch opened this issue Aug 29, 2019 · 2 comments · Fixed by #9719
Closed

v3 API docs #8087

htuch opened this issue Aug 29, 2019 · 2 comments · Fixed by #9719
Assignees
@htuch
Labels
api/v3 Major version release @ end of Q3 2019 no stalebot Disables stalebot from closing an issue
Milestone
1.13.0

Comments

@htuch
Copy link
Member

htuch commented Aug 29, 2019

Need to create v3 docs that live side-by-side with v2 docs. All references to v2 API fields need to be updated to v3 once we snap v3.
@htuch htuch added no stalebot Disables stalebot from closing an issue api/v3 Major version release @ end of Q3 2019 labels Aug 29, 2019
@htuch htuch added this to the 1.12.0 milestone Aug 29, 2019
@htuch htuch self-assigned this Aug 29, 2019
@htuch htuch mentioned this issue Aug 29, 2019
Closed
5 tasks
@htuch htuch modified the milestones: 1.12.0, 1.13.0 Oct 16, 2019
@htuch
Copy link
Member Author

htuch commented Jan 16, 2020

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:

  1. 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.
  2. 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?

@mattklein123
Copy link
Member

Yeah (1) SGTM.

htuch added a commit to htuch/envoy that referenced this issue Jan 17, 2020
@htuch
api/docs: v3 API reference documentation.
5a88371 
This PR introduces a parallel v3 API reference documentation tree to the
existing v2 one.

The docs/root/api-v3/ tree was copied from docs/root/api-v2 and the
necessary package path fixups were made manually. As a result, the tree
largely resembles the v2 docs. Long term this is likely to evolve to
reflect the shape of the new extensions tree.

The message type, field and enum anchors are sed'ed to be distinct and
self-consistent inside api-v3/.

There were a number of API proto changes that were made to obtain a
successful Sphinx build:
* References to deprecated fields were replaced by references to the
  replacement field.
* clang-format line wrapping in protoxform was removed, this breaks RST
  in some v3 protos.
* Some packages (type/metadata/v2, data/cluster/v2alpha) were force
  upgraded to v3, to deal with references to types that are distinct in
  v2/v3. This is OK as these packages probably make sense to bump for
  v3, in general we're going to have to think about how to do this more
  cleanly, supporting dual v2/v3 references alongside each other.
* Some evil hacks for field renaming added to migrate.py for
  RouteAction.

There's also some additional machinery added to compute distinct v3/v3
build targets to point protodoc at.

Risk level: Low
Testing: Docs build, manual inspection.

Fixes envoyproxy#8087

Signed-off-by: Harvey Tuch <[email protected]>
@htuch htuch mentioned this issue Jan 17, 2020
Merged
htuch added a commit that referenced this issue Jan 20, 2020
@htuch
api/docs: v3 API reference documentation. (#9719)
ac88316 
This PR introduces a parallel v3 API reference documentation tree to the
existing v2 one.

The docs/root/api-v3/ tree was copied from docs/root/api-v2 and the
necessary package path fixups were made manually. As a result, the tree
largely resembles the v2 docs. Long term this is likely to evolve to
reflect the shape of the new extensions tree.

The message type, field and enum anchors are sed'ed to be distinct and
self-consistent inside api-v3/.

There were a number of API proto changes that were made to obtain a
successful Sphinx build:

* References to deprecated fields were replaced by references to the replacement field.
* clang-format line wrapping in protoxform was removed, this breaks RST in some v3 protos.
* Some packages (type/metadata/v2, data/cluster/v2alpha) were force upgraded to v3, to deal with references to types that are distinct in v2/v3. This is OK as these packages probably make sense to bump for v3, in general we're going to have to think about how to do this more
cleanly, supporting dual v2/v3 references alongside each other.
* Some evil hacks for field renaming added to migrate.py for RouteAction.

There's also some additional machinery added to compute distinct v3/v3
build targets to point protodoc at.

Risk level: Low
Testing: Docs build, manual inspection.

Fixes #8087

Signed-off-by: Harvey Tuch <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@htuch htuch

Labels
api/v3 Major version release @ end of Q3 2019 no stalebot Disables stalebot from closing an issue
Projects
None yet
Milestone
1.13.0
Development

Successfully merging a pull request may close this issue.

api/docs: v3 API reference documentation. htuch/envoy
2 participants
@mattklein123 @htuch