envoyproxy/envoy

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

Open

#15.332 aperta il 5 mar 2021

Vedi su GitHub
 (6 commenti) (0 reazioni) (1 assegnatario)C++ (5373 fork)batch import
area/docshelp wanted

Metriche repository

Star
 (27.997 star)
Metriche merge PR
 (Merge medio 8g) (378 PR mergiate in 30 g)

Descrizione

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.

Guida contributor

Direzione di ricerca
Esamina la configurazione Sphinx esistente e la struttura della documentazione API per capire come vengono definite le referenze, poi progetta un plugin che aggiunga collegamenti hover dagli esempi di configurazione YAML/JSON alle sezioni API pertinenti.
Tech stack
python
Dominio
documentation
Tipo issue
Funzionalità
DifficoltàQuanto dovrebbe essere impegnativa per un nuovo contributor.
2
Tempo stimatoTempo stimato per completare e verificare uno scope piccolo.
Mezza giornata
Stato attivitàQuanto è probabile che la issue sia ancora attiva e reviewable.
Attiva
ChiarezzaQuanto chiaramente la issue descrive problema, scope e risultato atteso.
Chiara
Prerequisiti
PythonSphinx
Adatta ai principiantiQuanto la issue è adatta a contributor alla prima esperienza.
65