इस पेज पर, तकनीकी लेखन वाले उस प्रोजेक्ट की जानकारी दी गई है जिसे Google Season of Docs के लिए स्वीकार किया गया है.
प्रोजेक्ट की खास जानकारी
- ओपन सोर्स संगठन:
- Cloud Native Computing Foundation (CNCF)
- टेक्निकल राइटर:
- feloy
- प्रोजेक्ट का नाम:
- Kubernetes की वेबसाइट पर एपीआई रेफ़रंस दिखाने के तरीके को अपडेट करना
- प्रोजेक्ट की अवधि:
- स्टैंडर्ड अवधि (तीन महीने)
प्रोजेक्ट का विवरण
फ़िलहाल, Kubernetes API के रेफ़रंस, बड़े एचटीएमएल दस्तावेज़ हैं. इन्हें स्वैगर की खास जानकारी के आधार पर, वेबसाइट रिपॉज़िटरी के बाहर होस्ट की गई स्क्रिप्ट से जनरेट किया जाता है. इसके बाद, इन्हें वेबसाइट की रिपॉज़िटरी में जोड़ दिया जाता है.
दूसरी ओर, Kubernetes दस्तावेज़ों की वेबसाइट को Hugo की मदद से बनाया गया है. यह वेबसाइट, Docsy Hugo थीम का इस्तेमाल करके, वेबसाइट के रिपॉज़िटरी में मार्कडाउन फ़ॉर्मैट में लिखे गए दस्तावेज़ों से बनाई गई है.
इस प्रोजेक्ट का मकसद, दस्तावेज़ की वेबसाइट बनाने की प्रोसेस में Kubernetes API रेफ़रंस जनरेशन को इंटिग्रेट करना है.
खास तौर से, हम Docsy Hugo थीम के ज़रिए उपलब्ध कराए गए swaggerui शॉर्टकोड, swagger-ui के रैपर पर फ़ोकस करेंगे. साथ ही, Docsy Hugo थीम के ज़रिए उपलब्ध कराए गए खास टूलिंग पर फ़ोकस करेंगे, जिससे एपीआई की खास बातों के दस्तावेज़ के फ़्लो को शामिल करने की सुविधा चालू होगी.
इसके लिए, आपको किसी खास टूल की ज़रूरत होगी, क्योंकि swagger-ui, swagger फ़ाइल में बताई गई पूरी जानकारी को आउटपुट कर सकता है, लेकिन उसके कुछ हिस्सों को नहीं (देखें 8). Kubernetes API बहुत बड़ा है, इसलिए इसे सिर्फ़ एक हिस्से में नहीं दिखाया जा सकता (आउटपुट का उदाहरण). हम दो तरीकों पर विचार करेंगे:
पहला तरीका यह है कि (10) पर उपलब्ध सोर्स से, कई swagger फ़ाइलें बनाएं. हर Kubernetes API ग्रुप(core/v1, apps/v1, ...) के लिए एक फ़ाइल बनाएं. साथ ही, Kubernetes दस्तावेज़ की वेबसाइट में कुछ खास जगहों पर, इन फ़ाइलों को swaggerui sortcodes के इनपुट के तौर पर इस्तेमाल करें,
दूसरा तरीका यह है कि एक ऐसा टूल बनाएं जो (11) पर मौजूद Kubernetes API की पूरी swagger फ़ाइल को इनपुट के तौर पर ले और किसी खास एंडपॉइंट या सीमित संख्या में एंडपॉइंट और उससे जुड़े संसाधनों और परिभाषाओं के लिए नई swagger फ़ाइल को आउटपुट करे. इसके बाद, इन swagger फ़ाइलों का इस्तेमाल Kubernetes दस्तावेज़ की वेबसाइट में खास जगहों पर, swaggerui शॉर्टकोड के इनपुट के तौर पर करें.
स्पेसिफ़िकेशन (10 और 11) के सोर्स, दस्तावेज़ के सोर्स से अलग-अलग रिपॉज़िटरी में मौजूद होते हैं. इसलिए, हमें यह तरीका ढूंढना होगा कि जब भी इनमें बदलाव हो, तो उन्हें दस्तावेज़ रिपॉज़िटरी में अपने-आप अपडेट किया जा सके.
Kubernetes दस्तावेज़ अलग-अलग भाषाओं में उपलब्ध हैं. इसलिए, हम Kubernetes API रेफ़रंस के अनुवादों को पब्लिश करने पर खास ध्यान देंगे.