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.

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

[WIP] protodoc: Add previous version information #16299

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .azure-pipelines/pipelines.yml
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ stages:
BAZEL_REMOTE_INSTANCE: projects/envoy-ci/instances/default_instance
GCP_SERVICE_ACCOUNT_KEY: $(GcpServiceAccountKey)
displayName: "Generate docs"
continueOnError: true

- script: |
ci/run_envoy_docker.sh 'ci/upload_gcs_artifact.sh /source/generated/docs docs'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ option java_outer_classname = "HttpConnectionManagerProto";
option java_multiple_files = true;
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-redirect: config/filter/network/http_connection_manager/v2/http_connection_manager.proto]

// [#protodoc-title: HTTP connection manager]
// HTTP connection manager :ref:`configuration overview <config_http_conn_man>`.
// [#extension: envoy.filters.network.http_connection_manager]
Expand Down
4 changes: 4 additions & 0 deletions docs/build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,10 @@ rsync -av \
"${SCRIPT_DIR}"/_ext \
"${GENERATED_RST_DIR}"

# Merge generated redirects
cat /tmp/redirects.txt >> "${GENERATED_RST_DIR}"/redirects.txt
cat "${GENERATED_RST_DIR}"/redirects.txt

# To speed up validate_fragment invocations in validating_code_block
bazel build "${BAZEL_BUILD_OPTIONS[@]}" //tools/config_validation:validate_fragment

Expand Down
3 changes: 3 additions & 0 deletions tools/api_proto_plugin/annotations.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@
# Comment. Just used for adding text that will not go into the docs at all.
COMMENT_ANNOTATION = 'comment'

REDIRECT_ANNOTATION = "protodoc-redirect"

VALID_ANNOTATIONS = set([
DOC_TITLE_ANNOTATION,
EXTENSION_ANNOTATION,
Expand All @@ -38,6 +40,7 @@
NEXT_FREE_FIELD_ANNOTATION,
NEXT_MAJOR_VERSION_ANNOTATION,
COMMENT_ANNOTATION,
REDIRECT_ANNOTATION,
])

# These can propagate from file scope to message/enum scope (and be overridden).
Expand Down
22 changes: 20 additions & 2 deletions tools/protodoc/protodoc.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,15 @@
from tools.protodoc import manifest_pb2
from udpa.annotations import security_pb2
from udpa.annotations import status_pb2
from udpa.annotations import versioning_pb2
from validate import validate_pb2

# Namespace prefix for Envoy core APIs.
ENVOY_API_NAMESPACE_PREFIX = '.envoy.api.v2.'

# Last documented v2 api version
ENVOY_LAST_V2_VERSION = "1.17.2"

# Namespace prefix for Envoy top-level APIs.
ENVOY_PREFIX = '.envoy.'

Expand All @@ -57,7 +61,7 @@
"""
.. _extension_{{extension}}:

This extension may be referenced by the qualified name *{{extension}}*
This extension may be referenced by the qualified name ``{{extension}}``

.. note::
{{status}}
Expand Down Expand Up @@ -125,6 +129,9 @@
EXTENSION_CATEGORIES.setdefault(_cat, []).append(_k)


REDIRECTS_FILE = "/tmp/redirects.txt"


class ProtodocError(Exception):
"""Base error class for the protodoc module."""

Expand Down Expand Up @@ -681,7 +688,14 @@ def visit_message(self, msg_proto, type_context, nested_msgs, nested_enums):
formatted_leading_comment = format_comment_with_annotations(leading_comment, 'message')
if hide_not_implemented(leading_comment):
return ''
return anchor + header + proto_link + formatted_leading_comment + format_message_as_json(

previous_version = ""
if msg_proto.options.HasExtension(versioning_pb2.versioning):
_previous_version = msg_proto.options.Extensions[versioning_pb2.versioning].previous_message_type
_previous_version_url = f"v{ENVOY_LAST_V2_VERSION}:envoy_api_msg_{_previous_version.split('.')[1:]}"
previous_version = f".. tip::\n PREVIOUS VERSION: :ref:`{_previous_version} <{_previous_version_url}>`\n\n"

return anchor + header + proto_link + formatted_leading_comment + previous_version + format_message_as_json(
type_context, msg_proto) + format_message_as_definition_list(
type_context, msg_proto,
self.protodoc_manifest) + '\n'.join(nested_msgs) + '\n' + '\n'.join(nested_enums)
Expand All @@ -691,6 +705,10 @@ def visit_file(self, file_proto, type_context, services, msgs, enums):
if all(len(msg) == 0 for msg in msgs) and all(len(enum) == 0 for enum in enums):
has_messages = False

if annotations.REDIRECT_ANNOTATION in type_context.source_code_info.file_level_annotations:
with open(REDIRECTS_FILE, "a") as f:
f.write(f"api-v2/{type_context.source_code_info.file_level_annotations[annotations.REDIRECT_ANNOTATION]}.rst\tapi-v3/{'/'.join(file_proto.name.split('/')[1:])}.rst\n")

# TODO(mattklein123): The logic in both the doc and transform tool around files without messages
# is confusing and should be cleaned up. This is a stop gap to have titles for all proto docs
# in the common case.
Expand Down