envoyproxy/envoy

Add a sphinx plugin to allow linking from demo configurations to api sections

Open

#15,332 opened on Mar 5, 2021

View on GitHub
 (6 comments) (0 reactions) (1 assignee)C++ (5,373 forks)batch import
area/docshelp wanted

Repository metrics

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

Description

description

learning envoy configuration can be quite a steep learning curve and its not always easy to navigate the docs to find the relevant spec

im thinking it might be helpful if the config examples in the docs provided a click through to the relevant api section - perhaps if you hover over the line a link appears at the end, for example

depending on how fine grained the links were, i think we might need to add more ref links in the api to allow that

on a related point im noticing that all most of the api examples are json - whereas the config examples are mostly yaml. There are probably good reasons for both, but im thinking this is another way in which the docs can jar for new users.

Contributor guide

Research direction
Examine the existing Sphinx configuration and API documentation structure to understand how references are defined, then design a plugin that adds hover links from YAML/JSON config examples to relevant API sections.
Tech stack
python
Domain
documentation
Issue type
Feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Half day
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
PythonSphinx
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65