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