परफ़ॉर्मेंस को-पायलट प्रोजेक्ट

इस पेज पर, तकनीकी लेखन वाले उस प्रोजेक्ट की जानकारी दी गई है जिसे Google Season of Docs के लिए स्वीकार किया गया है.

प्रोजेक्ट की खास जानकारी

ओपन सोर्स संगठन:
परफ़ॉर्मेंस को-पायलट
टेक्निकल राइटर:
arzoo14
प्रोजेक्ट का नाम:
बुक प्रोजेक्ट के अलग-अलग सेक्शन के कॉन्टेंट को readthedocs और reStructuredText फ़ॉर्मैट में बदलें. साथ ही, डायग्राम को बेहतर बनाने के लिए स्ट्रेच गोल भी सेट करें.
प्रोजेक्ट की अवधि:
स्टैंडर्ड लंबाई (तीन महीने)

प्रोजेक्ट का विवरण

खास जानकारी:

कम्यूनिटी वेबसाइट, ओपन-सोर्स संगठन में अहम भूमिका निभाती है. इसकी मदद से, कम्यूनिटी के योगदान, उनकी स्किल, दस्तावेज़, ट्यूटोरियल वगैरह के बारे में जानकारी दी जाती है.इसलिए, मेरे प्रोजेक्ट का मकसद, ओपन-सोर्स में योगदान देने वाले सभी लोगों के लिए, किताब के प्रोजेक्ट एरिया के कॉन्टेंट को ट्रांसफ़र और अपडेट करके, उसे आसानी से इस्तेमाल करने लायक बनाना है. जैसे, docbook कॉन्टेंट, REST API दस्तावेज़, और pbench मार्कडाउन कॉन्टेंट को reStructuredText फ़ॉर्मैट में बदलना, ताकि इसे कम्यूनिटी की आधुनिक readthedocs.io साइट पर होस्ट किया जा सके. इस प्रोजेक्ट से, कम्यूनिटी में योगदान देने वाले लोगों को भी फ़ायदा मिलेगा. वे इस कॉन्टेंट में आसानी से बदलाव कर पाएंगे और उसे बड़ा भी कर पाएंगे. साथ ही, स्ट्रेच गोल के तौर पर, दस्तावेज़ में डायग्राम को बेहतर बनाया जाएगा, ताकि उन्हें ज़्यादा प्रोफ़ेशनल लुक दिया जा सके.

प्रस्ताव:

  1. खास जानकारी: परफ़ॉर्मेंस को-पायलट से जुड़ा दस्तावेज़, फ़िलहाल कई अलग-अलग फ़ॉर्मैट में उपलब्ध है. इनमें डॉकबुक फ़ॉर्मैट में पीसीपी बुक, मैनपेज फ़ॉर्मैट में REST API, और मार्कडाउन फ़ॉर्मैट में Pbench गाइड शामिल हैं. इसलिए, संगठन के मौजूदा मैनेजर ग्रुप ने यह तय किया कि उन्हें ऐसा समाधान चाहिए जिसे मैनेज करने में ज़्यादा समय न लगे. इससे डेवलपर कम्यूनिटी, अपने कॉन्टेंट को आसानी से मैनेज कर पाएगी. इसलिए, संगठन की मौजूदा ज़रूरतों के मुताबिक, मैं इस Google Season of Docs के दौरान ये लक्ष्य हासिल करूंगा:

    1. DocBook कॉन्टेंट को reStructuredText फ़ॉर्मैट में बदलना और उसे readthedocs साइट पर होस्ट करना.
    2. REST API के दस्तावेज़ को मैन पेज से डेवलपर के हिसाब से फ़ॉर्मैट में बदलना. जैसे, reStructuredText फ़ॉर्मैट में बदलना और उसे readthedocs साइट पर होस्ट करना.
    3. pbench MarkDown के कॉन्टेंट को restructuredText फ़ॉर्मैट में बदलना और उसे Readthedocs साइट पर होस्ट करना.
    4. दस्तावेज़ में मौजूद डायग्राम को बेहतर बनाने के लिए, ज़्यादा लक्ष्य तय किए जा सकते हैं.

  2. लागू करना: फ़िलहाल, परफ़ॉर्मेंस को-पायलट दस्तावेज़ किसी खास फ़ॉर्मैट में मौजूद नहीं है. जब भी दस्तावेज़ के कॉन्टेंट में बदलाव करना हो, तो उसे उपयोगकर्ताओं के सीमित ग्रुप को ही बदलना चाहिए. कम्यूनिटी के सक्रिय सदस्यों के लिए, दस्तावेज़ के कॉन्टेंट में बदलाव करना और उसे बड़ा करना आसान नहीं है.

मैं इस जीएसओडी के दौरान, reStructuredText फ़ॉर्मैट, Read the Docs (RTD), और Sphinx की मदद से, संगठन को इन सीमाओं से बाहर निकलने में मदद करूंगा.

सॉफ़्टवेयर से जुड़े दस्तावेज़ को आसान बनाने के लिए, Docs (RTD) को पढ़ें. इससे आपको हमारे दस्तावेज़ों को अपने-आप बनाने, वर्शन बनाने, और उन्हें होस्ट करने में मदद मिलती है. यह स्फ़िंक्स के जनरेट किए गए दस्तावेज़ों को होस्ट करने वाला प्लैटफ़ॉर्म है. यह Sphinx की सुविधाओं का इस्तेमाल करता है. साथ ही, इसमें वर्शन कंट्रोल, फ़ुल-टेक्स्ट सर्च, और अन्य काम की सुविधाएं भी जोड़ी गई हैं. यह Git, Mercurial या Subversion से कोड और दस्तावेज़ फ़ाइलें डाउनलोड करता है. इसके बाद, हमारे दस्तावेज़ों को बनाता और होस्ट करता है. हम अपने प्रोजेक्ट में GitHub का इस्तेमाल करेंगे, क्योंकि कोड ऐक्सेस करने के लिए, इसका इस्तेमाल सबसे ज़्यादा किया जाता है.

शुरू करने के लिए, हम Read the Docs खाता बनाएंगे और GitHub खाता लिंक करेंगे. इसके बाद, हम GitHub रिपॉज़िटरी को चुनेंगे, जिसके लिए हमें दस्तावेज़ बनाना है. ऐसा तब होगा, जब यह काम आसान हो जाएगा.

Read the Docs: - हमारे रिपॉज़िटरी को क्लोन करेगा. - हमारी मास्टर ब्रांच से हमारे दस्तावेज़ के HTML, PDF, और ePub वर्शन बनाएं. - पूरे टेक्स्ट को खोजने की सुविधा देने के लिए, हमारे दस्तावेज़ों को इंडेक्स करें. - हमारी रिपॉज़िटरी में मौजूद हर टैग और शाखा से वर्शन ऑब्जेक्ट बनाएं. इससे, हम उन्हें वैकल्पिक तौर पर होस्ट कर सकते हैं. - हमारी रिपॉज़िटरी पर वेबहुक चालू करें, ताकि जब हम किसी शाखा में कोड को पुश करें, तो हमारा दस्तावेज़ फिर से बन जाए.

Sphinx, दस्तावेज़ जनरेट करने वाला एक आधिकारिक टूल है. इसमें तकनीकी दस्तावेज़ लिखने के लिए कई बेहतरीन सुविधाएं हैं. जैसे: - एक ही सोर्स से वेब पेज, प्रिंट किए जा सकने वाले PDF, ई-रीडर (ePub) के लिए दस्तावेज़ वगैरह जनरेट करना. - हम दस्तावेज़ लिखने के लिए, restructuredText का इस्तेमाल कर सकते हैं. - क्रॉस-रेफ़रंसिंग कोड और दस्तावेज़ का एक बड़ा सिस्टम. - सिंटैक्स हाइलाइट किए गए कोड सैंपल. - पहले और तीसरे पक्ष के एक्सटेंशन का बेहतर नेटवर्क.

मैं docbook फ़ॉर्मैट में मौजूद दो PCP किताबों को rst फ़ॉर्मैट में बदलने से शुरुआत करूंगा. इसके बाद, REST API दस्तावेज़ को मैन पेज फ़ॉर्मैट से rst फ़ॉर्मैट में बदलूंगा. इसके बाद, pbench मार्कडाउन कॉन्टेंट को rst फ़ॉर्मैट में बदलूंगा. आखिर में, इन सभी को readthedocs साइट पर होस्ट करूंगा. स्ट्रेच लक्ष्य के तौर पर, दस्तावेज़ में डायग्राम को बेहतर बनाया जाएगा.

2.1. reStructuredText फ़ॉर्मैट में बदलना: सबसे पहले, दस्तावेज़ के कॉन्टेंट को reStructuredText फ़ॉर्मैट में बदलना होगा. हर चैप्टर के लिए एक अलग rst फ़ाइल होगी, जिसमें सिर्फ़ उस चैप्टर का कॉन्टेंट होगा. उदाहरण के लिए, परफ़ॉर्मेंस को-पायलट यूज़र और एडमिन की गाइड की किताब में आठ चैप्टर हैं. इसका मतलब है कि उन आठ चैप्टर के लिए आठ अलग-अलग rst फ़ाइलें होंगी. आने वाले समय में किसी भी तरह की उलझन से बचने के लिए rst फ़ाइल का नाम ही चैप्टर का नाम होगा. आंकड़ों, टेबल, और उदाहरणों की सूचियां तीन अलग-अलग rst फ़ाइलों में होंगी. आरएसटी कॉन्टेंट को उसी तरह से पूरी तरह हाइपरलिंक किया जाएगा जिस तरह से वह फ़िलहाल मौजूद है. REST API दस्तावेज़ और pbench कॉन्टेंट के लिए भी यही तरीका इस्तेमाल किया जाएगा. कॉन्टेंट को rst फ़ॉर्मैट में बदलते समय, बोल्ड, इटैलिक, अंडरलाइन, बुलेट पॉइंट, टेबल, फ़ॉन्ट साइज़, कोड-स्टाइल, इमेज साइज़, अलाइनमेंट वगैरह जैसी सभी ज़रूरी चीज़ों का ध्यान रखा जाएगा.

2.2. Sphinx के साथ rst का इंटिग्रेशन:

ReadtheDocs, डिफ़ॉल्ट रूप से Sphinx और reStructuredText (rst) का इस्तेमाल करता है. मेरे सिस्टम में Sphinx पहले से इंस्टॉल है. इसलिए, मैं दस्तावेज़ों को सेव करने के लिए, प्रोजेक्ट में एक डायरेक्ट्री (जिसे परफ़ॉर्मेंस को-पायलट दस्तावेज़ कहा जाता है) बनाऊंगा: $ cd /path/to/project $ mkdir docs

इसके बाद, उसमें sphinx-quickstart चलाएं: $ cd docs $ sphinx-quickstart

इस शुरुआती लेख में, ज़रूरी कॉन्फ़िगरेशन बनाने के बारे में बताया गया है. ज़्यादातर मामलों में, हम डिफ़ॉल्ट कॉन्फ़िगरेशन को स्वीकार कर सकते हैं. हालांकि, ज़रूरत पड़ने पर, हम कॉन्फ़िगरेशन फ़ाइल में ज़रूरी बदलाव कर सकते हैं. इसके पूरा होने पर, हमारे पास index.rst, conf.py, और कुछ अन्य फ़ाइलें होंगी. index.rst में, मैं परफ़ॉर्मेंस को-पायलट की सभी ज़रूरी जानकारी जोड़ दूंगा. साथ ही, मैं किताबों, REST API दस्तावेज़, और पंच गाइड, दोनों के लिए हेडिंग बनाऊंगा/बनाऊंगी. जब कोई उपयोगकर्ता किसी हेडिंग पर क्लिक करेगा, तो उस हेडिंग के तहत मौजूद सभी दस्तावेज़ खुल जाएंगे.

ध्यान दें: इंडेक्स पेज का डिज़ाइन, मेंटर और कम्यूनिटी के सदस्यों की सहमति के हिसाब से होगा. साथ ही, ज़रूरतों और शर्तों के हिसाब से उसमें बदलाव किया जाएगा.

index.rst को हमारे दस्तावेज़ की आउटपुट डायरेक्ट्री (आम तौर पर _build/html/index.html) में index.html में बनाया जाएगा. सार्वजनिक रिपॉज़िटरी में Sphinx दस्तावेज़ होने के बाद, अपने दस्तावेज़ इंपोर्ट करके Read the Docs का इस्तेमाल शुरू किया जा सकता है.

जब हम अपने दस्तावेज़ में कोई .rst फ़ाइल जोड़ेंगे, तो उस फ़ाइल के हिसाब से तीन अन्य फ़ाइलें जनरेट होंगी. इनमें से एक फ़ाइल, .doctree एक्सटेंशन के साथ doctrees फ़ोल्डर में, दूसरी फ़ाइल .html एक्सटेंशन के साथ Html फ़ोल्डर में, और तीसरी फ़ाइल .rst.txt एक्सटेंशन के साथ html/_sources फ़ोल्डर में जनरेट होगी.

  1. दस्तावेज़ होस्ट करना: इंटरनेट पर दस्तावेज़ होस्ट करने के दो चरण होते हैं: 1. दस्तावेज़ इंपोर्ट करना: सबसे पहले, मैं Read The Docs खाते को GitHub से कनेक्ट करूंगा और दस्तावेज़ बनाने के लिए, अपना दस्तावेज़ प्रोजेक्ट इंपोर्ट करूंगा. 2. दस्तावेज़ बनाना: इंपोर्ट की प्रोसेस पूरी होने के कुछ सेकंड के अंदर, कोड हमारे सार्वजनिक रिपॉज़िटरी से अपने-आप फ़ेच हो जाएगा और दस्तावेज़ बन जाएगा.

  2. WEBHOOKS: वेबहुक का इस्तेमाल करके दस्तावेज़ और वर्शन में हुए बदलावों का पता लगाने के लिए, Docs में 'पढ़ें' मुख्य तरीका इस्तेमाल होता है. Webhooks को GitHub जैसी हमारी रिपॉज़िटरी सेवा देने वाली कंपनी के साथ कॉन्फ़िगर किया जाता है. साथ ही, हमारी रिपॉज़िटरी में किए गए हर कमिट, मर्ज या अन्य बदलाव के बारे में Read the Docs को सूचना दी जाती है. जब हमें कोई वेबहुक सूचना मिलती है, तो हम यह तय करते हैं कि यह बदलाव हमारे प्रोजेक्ट के किसी चालू वर्शन से जुड़ा है या नहीं. अगर ऐसा होता है, तो उस वर्शन के लिए बिल्ड ट्रिगर होता है.

इस तरह, एडमिन, मेंटर, और कम्यूनिटी में योगदान देने वाले लोग, कम्यूनिटी के दस्तावेज़ में बदलाव कर सकते हैं, उन्हें बड़ा कर सकते हैं या उन्हें मैनेज कर सकते हैं. साथ ही, यह तय करने के लिए कि दस्तावेज़ में क्या जोड़ना है या उससे क्या हटाना है, किसी खास ग्रुप के उपयोगकर्ताओं की ज़रूरत नहीं होगी.

  1. थीम: थीम, लेआउट, डिज़ाइन, और खोज जैसी अन्य एचटीएमएल सुविधाएं, समुदाय की ज़रूरतों और दिशा-निर्देशों के मुताबिक होंगी. कम्यूनिटी बॉन्डिंग पीरियड के दौरान, मैं इन सभी बातों पर कम्यूनिटी के सदस्यों के साथ चर्चा करूंगा.
  1. स्ट्रेच गोल: स्ट्रेच गोल के तौर पर, मैं दस्तावेज़ में मौजूद डायग्राम को बेहतर बनाऊंगा. फ़िलहाल, डायग्राम ज़्यादातर ब्लैक ऐंड व्हाइट ड्रॉइंग होते हैं. मैं इमेज में ज़्यादा रंग, शेडिंग, स्केलिंग, और एक जैसा स्टाइल लागू करूँगी. साथ ही, इमेज को सामान्य तौर पर साफ़ / ज़्यादा प्रोफ़ेशनल लुक देना शुरू करूँगी.

इस मकसद के लिए, मैं draw.io का इस्तेमाल करूंगा. इसके अलावा, मैं मेंटर की सहमति लेकर किसी दूसरे टूल का भी इस्तेमाल कर सकता/सकती हूं.

कॉन्सेप्ट की पुष्टि करने के लिए, मैंने दस्तावेज़ में मौजूद एक डायग्राम को बेहतर बनाया है. इसके लिए, मैंने draw.io का इस्तेमाल किया है. कृपया इसे यहां पाएं: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

कॉन्सेप्ट का सबूत

मैंने PCP की किताब (docbook फ़ॉर्मैट) के एक छोटे हिस्से को rst फ़ॉर्मैट में बदल दिया है और उसे readthedocs साइट पर होस्ट किया है. कृपया इसे यहां देखें.

वेबसाइट - https://pcp-books.readthedocs.io/en/latest/ कोड - https://github.com/arzoo14/PCP_Books_Demo

मैंने कोड रिपॉज़िटरी में वेबहुक भी कॉन्फ़िगर किए हैं. इनकी मदद से, कोड रिपॉज़िटरी में किए गए बदलाव, वेबसाइट में दिखेंगे.

टाइमलाइन और डिलीवर किए जाने वाले आइटम

कम्यूनिटी बॉन्डिंग की अवधि [ 17 अगस्त से 13 सितंबर, 2020 ]

इस दौरान मुझे कम्यूनिटी के बारे में जानकारी मिलेगी, उससे जुड़े दस्तावेज़ पढ़ेंगे, और मेंटॉर के साथ कई चीज़ों पर चर्चा करनी होगी. इससे यह पक्का किया जा सकेगा कि प्रोसेस के दौरान कोई गलत फ़ैसला न लिया जाए. इस दौरान, मैं मेंटर और कम्यूनिटी के सदस्यों के साथ थीम, लेआउट, डिज़ाइन, और खोज, नेविगेशन बार जैसी अन्य सुविधाओं के बारे में बातचीत करूंगा. प्रोजेक्ट के नाम और तीनों विषयों को होस्ट करने के लिए एक ही वेबसाइट होगी या नहीं, इस पर तीन विषयों से जुड़ी तीन अलग-अलग वेबसाइटें होंगी, इस बारे में कम्यूनिटी बॉन्डिंग के दौरान लिए गए फ़ैसले पर चर्चा की जाएगी.

डीओसी डेवलपमेंट पीरियड [ 14 सितंबर - 30 नवंबर, 2020 ]

***14 सितंबर, 2020 से 20 सितंबर, 2020 [पहला हफ़्ता] उपयोगकर्ताओं और एडमिन के लिए गाइड वाली किताब के पहले चार चैप्टर के लिए, docbook कॉन्टेंट को rst फ़ॉर्मैट में बदलना.

***21 सितंबर, 2020 से 27 सितंबर, 2020 [दूसरा हफ़्ता] उपयोगकर्ताओं और एडमिन के लिए गाइड वाली किताब के अगले चार चैप्टर के लिए, डॉकबुक कॉन्टेंट को rst फ़ॉर्मैट में बदलना.

***28 सितंबर, 2020 से 4 अक्टूबर, 2020 [तीसरा हफ़्ता] प्रोग्रामर गाइड बुक के चारों चैप्टर के लिए, docbook कॉन्टेंट को rst फ़ॉर्मैट में बदलना.

***5 अक्टूबर, 2020 से 11 अक्टूबर, 2020 [चौथा हफ़्ता] - readthedocs साइट पर, पीसीपी की दोनों किताबों को होस्ट करना. - REST API दस्तावेज़ को मैन पेज से rst फ़ॉर्मैट में बदलना. इस दौरान, मुख्य लैंडिंग पेज को कवर किया जाएगा. - पिछले तीन हफ़्तों और मौजूदा हफ़्ते में, मेरे GSoD प्रोजेक्ट के बारे में ब्लॉगिंग की.

***12 अक्टूबर, 2020 से 18 अक्टूबर, 2020 [पांचवां हफ़्ता] स्केलेबल टाइम सीरीज़ इंडेक्स को rst फ़ॉर्मैट में बदलना. स्केलेबल टाइम सीरीज़ इंडेक्स में ये चीज़ें शामिल हैं: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metric , GET /series/sources , GET /series/instances , GET /series/loads

***19 अक्टूबर, 2020 से 25 अक्टूबर, 2020 [छठा हफ़्ता] PMAPI होस्ट सेवाओं के इंडेक्स को rst फ़ॉर्मैट में बदलना. PMAPI होस्ट सेवाओं के इंडेक्स में ये चीज़ें शामिल हैं: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/kids GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/मेट्रिक

***26 अक्टूबर, 2020 से 1 नवंबर, 2020 [सातवां हफ़्ता] - अगर पिछले हफ़्तों में कुछ भी बचा है, तो उसे पहले कवर किया जाएगा. - readthedocs साइट पर REST API दस्तावेज़ होस्ट करना. - पिछले दो हफ़्तों और मौजूदा हफ़्ते के लिए, मेरे GSoD प्रोजेक्ट के बारे में ब्लॉगिंग.

***2 नवंबर, 2020 से 8 नवंबर, 2020 [आठवां हफ़्ता] pbench गाइड के लिए, मार्कडाउन कॉन्टेंट को आरएसटी फ़ॉर्मैट में बदलना.

***9 नवंबर, 2020 से 15 नवंबर, 2020 [नौवां हफ़्ता] - pbench गाइड के लिए, मार्कडाउन कॉन्टेंट को आरएसटी फ़ॉर्मैट में बदलने की प्रोसेस जारी रखी गई. - readthedocs साइट पर pbench गाइड को होस्ट करना. - पिछले हफ़्ते और मौजूदा हफ़्ते की ब्लॉगिंग (मेरे GSoD प्रोजेक्ट की).

***16 नवंबर, 2020 से 22 नवंबर, 2020 तक [WEEK 10] - वेबसाइटों के नाम से किसी भी कॉन्टेंट को खोजने के लिए, इंडेक्स पेज में खोजने की सुविधा लागू की गई है. - स्ट्रेच गोल की शुरुआत.

***23 नवंबर, 2020 से 30 नवंबर, 2020 [11वां हफ़्ता] - दस्तावेज़ में मौजूद सभी डायग्राम को बेहतर बनाया गया. - पिछले और मौजूदा हफ़्ते के लिए, मेरे GSoD प्रोजेक्ट की आखिरी ब्लॉगिंग. - यह जांच करना कि कोडबेस, कोडिंग स्टैंडर्ड के मुताबिक है या नहीं. अगर ऐसा नहीं है, तो उन्हें स्टैंडर्ड के मुताबिक बदलें.

प्रोजेक्ट के फ़ाइनल होने की अवधि [ 30 नवंबर से 5 दिसंबर, 2020 ]

  • पेंसिल का डाउनटाइम. आखिरी सबमिशन पर काम किया जा रहा है और यह पक्का किया जा रहा है कि सब कुछ ठीक है.
  • प्रोजेक्ट रिपोर्ट सबमिट करना. इन्हें फ़ाइनल वर्क प्रॉडक्ट भी कहा जाता है.
  • प्रोजेक्ट की सफलता और मेंटर के साथ काम करने के अनुभव का आकलन सबमिट करना.