Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- Cloud Native Computing Foundation (CNCF)
- Redattore tecnico:
- feloy
- Nome del progetto:
- Aggiornamento della modalità di pubblicazione dei riferimenti all'API sul sito web di Kubernetes
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Attualmente, i riferimenti all'API Kubernetes sono documenti HTML di grandi dimensioni generati dalle specifiche Swagger tramite script ospitati al di fuori del repository del sito web e poi aggiunti a questo repository.
D'altra parte, il sito web della documentazione di Kubernetes è creato con Hugo dalla documentazione scritta in formato Markdown nel repository del sito web, utilizzando il tema Hugo Docsy.
L'obiettivo di questo progetto è integrare la generazione dei riferimenti all'API Kubernetes nel processo di creazione del sito web della documentazione.
In particolare, ci concentreremo sullo swaggerui shortcode, il wrapper attorno a swagger-ui, fornito dal tema Docsy Hugo e sugli strumenti specifici, che consente l'inserimento di parti della specifica dell'API nel flusso della documentazione di Kubernetes.
Saranno necessari strumenti specifici perché swagger-ui è in grado di generare la specifica completa descritta in un file swagger, ma non parti di essa (vedi 8). L'API Kubernetes è troppo grande per essere visualizzata in una sola 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 utilizzare questi file come input di sortcode swaggerui in punti specifici del sito web della documentazione Kubernetes,
Il secondo approccio consiste nel creare uno strumento che riceva come input il file swagger completo dell'API Kubernetes disponibile all'indirizzo (11) e generi un nuovo file swagger per un endpoint specifico o un numero limitato di endpoint, nonché le relative risorse e definizioni, per poi utilizzare questi file swagger come input degli shortcode di swaggerui in punti specifici del sito web della documentazione di Kubernetes.
Poiché le origini delle specifiche (10 e 11) si trovano in altri repository rispetto alle origini della documentazione, dovremo trovare un modo per aggiornarle automaticamente nel repository della documentazione quando cambiano.
Poiché la documentazione di Kubernetes è disponibile in diverse lingue, presteremo particolare attenzione alla possibilità di pubblicare traduzioni per la documentazione di riferimento dell'API Kubernetes.