envoyproxy/envoy

Extension matcher documentation doesn't generate a link to the xds Matcher type

Open

#18,154 opened on Sep 17, 2021

View on GitHub
 (5 comments) (0 reactions) (1 assignee)C++ (5,373 forks)batch import
area/docsbughelp wantedno stalebot

Repository metrics

Stars
 (27,997 stars)
PR merge metrics
 (Avg merge 8d) (378 merged PRs in 30d)

Description

Title: Extension matcher documentation doesn't generate a link to the xds Matcher type

Description:

In the extension matcher docs, the documentation generator doesn't generate a reference link for the xds.type.matcher.v3.Matcher.

The actual sphinx doc looks like this. Note How there is no :ref: generated for the xds.type.matcher.v3.Matcher type:

.. code-block:: json

  {
    "matcher": "{...}",
    "xds_matcher": "{...}",
    "extension_config": "{...}"
  }

.. _envoy_v3_api_field_extensions.common.matching.v3.ExtensionWithMatcher.matcher:

matcher
  (:ref:`config.common.matcher.v3.Matcher <envoy_v3_api_msg_config.common.matcher.v3.Matcher>`) The associated matcher. This is deprecated in favor of xds_matcher.
  
  
.. _envoy_v3_api_field_extensions.common.matching.v3.ExtensionWithMatcher.xds_matcher:

xds_matcher
  (.xds.type.matcher.v3.Matcher) The associated matcher.
  
  
.. _envoy_v3_api_field_extensions.common.matching.v3.ExtensionWithMatcher.extension_config:

extension_config
  (:ref:`config.core.v3.TypedExtensionConfig <envoy_v3_api_msg_config.core.v3.TypedExtensionConfig>`, *REQUIRED*) The underlying extension config.

Contributor guide

Research direction
Inspect the protobuf documentation generation script (likely using Sphinx and protoc gen doc) to understand why the `xds.type.matcher.v3.Matcher` type is not generating a `:ref:` link. Look for how other types get their references and fix the missing mapping or annotation.
Tech stack
python
Domain
documentationdeveloper experience
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
1
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitDocumentation generation tools (Sphinx)
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85