Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Cloud Native Computing Foundation (CNCF)
- Technical writer:
- feloy
- Nome progetto:
- Aggiornare le modalità di utilizzo dei riferimenti API nel sito web di Kubernetes
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Attualmente, i riferimenti dell'API Kubernetes sono documenti HTML di grandi dimensioni generati da specifiche Swagger da script ospitati all'esterno del repository del sito web e poi aggiunti a questo repository di siti web.
Per quanto riguarda l'altro, il sito web della documentazione di Kubernetes viene creato con Hugo a partire dalla documentazione scritta in formato Markdown nel repository del sito web, utilizzando il tema di Docsy Hugo.
L'obiettivo di questo progetto è integrare la generazione dei riferimenti dell'API Kubernetes nel processo che crea il sito web della documentazione.
Nello specifico, ci concentreremo sullo shortcode swaggerui, sull'wrapper swagger-ui, fornito dal tema Docsy Hugo, e su strumenti specifici, che consentono l'inserimento di parti della specifica API nel flusso della documentazione di Kubernetes.
Saranno necessari strumenti specifici, in quanto swagger-ui sarà in grado di generare la specifica completa descritta in un file spavaldo, ma non parti di essa (vedi 8). L'API Kubernetes è troppo grande per essere visualizzata solo in una parte (un esempio di output). Prenderemo in considerazione due approcci:
il primo approccio consiste nel creare diversi file swaggerui, uno per ogni gruppo di API Kubernetes (core/v1, apps/v1, ...) da origini disponibili in (10), e utilizzarli come input di codici di ordinamento swaggerui in punti specifici nel sito web della documentazione di Kubernetes.
Il secondo approccio consiste nel creare uno strumento che riceva come input il file completo di spavalderia dell'API Kubernetes che si trova all'indirizzo (11) e che restituisce un nuovo file di spavalderia per un endpoint specifico o un numero limitato di endpoint, con le relative risorse e definizioni associate, per poi utilizzare questi file come input di codici spaventosi in punti specifici nel sito web della documentazione di Kubernetes.
Poiché le origini delle specifiche (10 e 11) risiedono in altri repository oltre alle origini della documentazione, dovremo trovare un modo per aggiornarle automaticamente nel repository della documentazione quando cambiano.
Poiché la documentazione di Kubernetes è disponibile in diversi linguaggi, prestiamo particolare attenzione alla possibilità di pubblicare traduzioni per il riferimento dell'API Kubernetes.