🍒 👩🏽 🌑 कोड के रूप में डॉक्स। भाग 1: अद्यतन को स्वचालित करें 🥔 🎴 👱🏿

बड़ी परियोजनाओं में, दसियों और सैकड़ों बातचीत सेवाओं से मिलकर, कोड के रूप में प्रलेखन के लिए एक दृष्टिकोण - कोड के रूप में डॉक्स - तेजी से अनिवार्य होता जा रहा है।

मैं दिखाऊंगा कि आप इस दर्शन को वर्गीकृत-सेवा की वास्तविकताओं में कैसे लागू कर सकते हैं, या इसके बजाय, मैं इसके कार्यान्वयन के पहले चरण से शुरू करूंगा: प्रलेखन में डेटा अपडेट करने का स्वचालन।

टूल किट

"कोड के रूप में दस्तावेज़ीकरण" का सिद्धांत कोड बनाते समय दस्तावेज़ लिखते समय समान टूल के उपयोग का अर्थ है: पाठ मार्कअप भाषा, संस्करण नियंत्रण प्रणाली, कोड समीक्षा और ऑटो-परीक्षण। मुख्य लक्ष्य: अंतिम परिणाम पर एक साथ काम करने के लिए पूरी टीम के लिए परिस्थितियां बनाना - एक पूर्ण ज्ञान आधार और व्यक्तिगत उत्पाद सेवाओं के उपयोग पर निर्देश। आगे, मैं उन विशिष्ट उपकरणों के बारे में बात करूँगा, जिन्हें हमने इस समस्या को हल करने के लिए चुना है।

एक पाठ मार्कअप भाषा के रूप में, हमने सबसे सार्वभौमिक - reStructuredText का उपयोग करने का निर्णय लिया। बड़ी संख्या में निर्देशों के अलावा, जो संरचना पाठ के लिए सभी बुनियादी कार्य प्रदान करते हैं, यह भाषा मुख्य अंतिम स्वरूपों का समर्थन करती है, जिसमें हमारी परियोजना के लिए आवश्यक HTML भी शामिल है।

Sphinx प्रलेखन जनरेटर का उपयोग करके फ़ाइलें .rst से .html में परिवर्तित हो जाती हैं। यह आपको स्थैतिक साइट बनाने की अनुमति देता है जिसके लिए आप अपनी खुद की बना सकते हैं या रेडीमेड थीम का उपयोग कर सकते हैं। हमारी परियोजना दो तैयार विषयों का उपयोग करती है - स्टैनफोर्ड-थीम और बूटस्ट्रैप-थीम । दूसरे में सबटॉपिक्स शामिल हैं जो आपको कुंजी इंटरफ़ेस तत्वों के लिए अलग-अलग रंग योजनाएं सेट करने की अनुमति देते हैं।

प्रलेखन के वर्तमान संस्करण के लिए सुविधाजनक और त्वरित पहुंच के लिए, हम विकास टीम के स्थानीय क्षेत्र नेटवर्क से सुलभ एक आभासी मशीन द्वारा होस्ट की गई स्थैतिक साइट का उपयोग करते हैं।

परियोजना की स्रोत फाइलें बिटबकेट रिपॉजिटरी में संग्रहीत हैं, और साइट केवल मास्टर शाखा में निहित फाइलों से उत्पन्न होती है। इसमें डेटा को अपडेट करना केवल पुल-अनुरोध के माध्यम से संभव है, जो आपको सार्वजनिक डोमेन में प्रकाशित होने से पहले प्रलेखन के सभी नए अनुभागों की जांच करने की अनुमति देता है।

चूंकि प्रलेखन के एक नए खंड को पूरा करने और साइट पर भेजने के बीच इसकी सामग्री की जांच करना आवश्यक है, इसलिए पूरी श्रृंखला में महत्वपूर्ण प्रक्रिया साइट के निर्माण और मेजबान पर डेटा को अपडेट करने की प्रक्रिया है। परियोजना के मुख्य शाखा के साथ अद्यतन मर्ज के साथ पुल-अनुरोध के बाद इस प्रक्रिया को हर बार दोहराया जाना चाहिए।

इस तर्क को लागू करने के लिए जेनकींस - हमारे मामले में विकास के निरंतर एकीकरण की एक प्रणाली - प्रलेखन की अनुमति देता है। मैं आपको वर्गों में सेटिंग्स के बारे में अधिक बताऊंगा:

जेनकिंस में एक नया नोड जोड़ना

साइट पर प्रलेखन का निर्माण और अद्यतन करने के लिए, आपको इसके लिए जेनकिंस एजेंट के रूप में पहले से तैयार मशीन को पंजीकृत करना होगा।

मशीन की तैयारी

जेनकिंस आवश्यकताओं के अनुसार, सिस्टम में शामिल सभी घटक, जिसमें मास्टर मशीन और सभी पंजीकृत एजेंट नोड्स शामिल हैं, के पास JDK या JRE स्थापित होना चाहिए। हमारे मामले में, JDK 8 का उपयोग किया जाएगा, जिसकी स्थापना के लिए यह कमांड चलाने के लिए पर्याप्त है:

sudo apt-get -y install java-1.8.0-openjdk git

मास्टर मशीन उस पर असाइन किए गए कार्यों को करने के लिए एजेंट से कनेक्ट होगी। ऐसा करने के लिए, आपको एजेंट पर एक उपयोगकर्ता बनाने की आवश्यकता है, जिसके तहत सभी ऑपरेशन किए जाएंगे, और जिसमें सभी जेनकिन्स- जनरेटेड फ़ाइलों को होम फ़ोल्डर में संग्रहीत किया जाएगा। लिनक्स सिस्टम पर, बस कमांड चलाएँ:

 sudo adduser jenkins \--shell /bin/bash su jenkins

मास्टर मशीन और एजेंट के बीच संबंध स्थापित करने के लिए, आपको SSH को कॉन्फ़िगर करना होगा और आवश्यक प्राधिकरण कुंजियों को जोड़ना होगा। हम एजेंट पर कुंजियाँ उत्पन्न करेंगे, जिसके बाद हम सार्वजनिक कुंजी को jenkins उपयोगकर्ता के लिए अधिकृत_की फ़ाइल में जोड़ देंगे ।

हम एक डॉक कंटेनर में प्रलेखन के साथ एक तैयार अजगर छवि का उपयोग करके साइट का निर्माण करेंगे : 3.7 । एजेंट पर डॉकर को स्थापित करने के लिए आधिकारिक दस्तावेज में दिए गए निर्देशों का पालन करें। स्थापना प्रक्रिया को पूरा करने के लिए, आपको एजेंट को फिर से कनेक्ट करना होगा। परीक्षण छवि लोड करने वाले कमांड को चलाकर स्थापना को सत्यापित करें:

 docker run hello-world

सुपरसकर (सुडो) की ओर से डॉकर कमांड को न चलाने के लिए, यह इंस्टॉलेशन स्टेज पर बनाए गए उपयोगकर्ता डॉकटर समूह को जोड़ने के लिए पर्याप्त है, जिसकी ओर से कमांड निष्पादित किए जाएंगे।

 sudo usermod -aG docker $USER

जेनकिंस नया नोड कॉन्फ़िगरेशन

चूंकि एजेंट से कनेक्ट करने के लिए प्राधिकरण की आवश्यकता होती है, इसलिए आपको जेनकिंस सेटिंग्स में उपयुक्त क्रेडेंशियल्स जोड़ना होगा। विंडोज मशीनों पर ऐसा करने के लिए विस्तृत निर्देश आधिकारिक जेनकिंस प्रलेखन में प्रदान किए गए हैं।

महत्वपूर्ण: कॉन्फ़िगर जेनकिन्स अनुभाग में निर्दिष्ट पहचानकर्ता -> बिल्ड वातावरण प्रबंधित करें -> नोड नाम -> टैग पैरामीटर में कॉन्फ़िगर का उपयोग एजेंट को इंगित करने के लिए जेनकिंसफाइल में किया जाता है जिस पर सभी ऑपरेशन किए जाएंगे।

जेनकिंसफाइल का वर्णन

प्रोजेक्ट रिपॉजिटरी की जड़ में जेनकिंसफाइल शामिल है, जिसमें निम्नलिखित निर्देश हैं:

बिल्ड वातावरण तैयार करना और निर्भरता स्थापित करना
स्फिंक्स का उपयोग करके एक साइट बनाएं
अद्यतन होस्ट जानकारी।

निर्देश विशेष निर्देशों का उपयोग करके निर्धारित किए जाते हैं, जिनमें से आवेदन हम परियोजना में उपयोग की गई फ़ाइल के उदाहरण पर आगे विचार करेंगे।

एजेंट संकेत

जेनकिंसफाइल की शुरुआत में , जेनकिंस में एजेंट के लेबल को निर्दिष्ट करें, जिस पर सभी ऑपरेशन किए जाएंगे। ऐसा करने के लिए, एजेंट निर्देश का उपयोग करें:

 agent { label '-' }

पर्यावरण की तैयारी

स्फिंक्स-बिल्ड साइट बिल्ड कमांड को निष्पादित करने के लिए, आपको पर्यावरण चर सेट करने की आवश्यकता है जिसमें वास्तविक डेटा पथ संग्रहीत किए जाएंगे। इसके अलावा, होस्ट पर जानकारी को अपडेट करने के लिए, आपको उन रास्तों को पहले से निर्दिष्ट करना होगा जहां प्रलेखन के साथ साइट डेटा संग्रहीत है। पर्यावरण निर्देश आपको इन मूल्यों को चरों पर नियत करने की अनुमति देता है:

 environment { SPHINX_DIR = '.' //,    Sphinx BUILD_DIR = 'project_home_built' //    SOURCE_DIR = 'project_home_source' //   .rst  .md  DEPLOY_HOST = 'username@127.1.1.0:/var/www/html/' //@IP__:__ }

मुख्य क्रियाएं

जेनकिंसफाइल में निष्पादित किए जाने वाले मुख्य निर्देश चरणों के निर्देशों के भीतर समाहित हैं, जिसमें चरण निर्देशों द्वारा वर्णित विभिन्न चरणों शामिल हैं। तीन-चरण सीआई-पाइपलाइन का एक सरल उदाहरण:

 pipeline { agent any stages { stage('Build') { steps { echo 'Building..' } } stage('Test') { steps { echo 'Testing..' } } stage('Deploy') { steps { echo 'Deploying....' } } } }

डॉकटर कंटेनर लॉन्च करें और निर्भरताएं स्थापित करें

सबसे पहले, समाप्त अजगर छवि के साथ डॉकर कंटेनर को चलाएं : 3.7 । ऐसा करने के लिए, --rm और -i झंडे के साथ docker रन कमांड का उपयोग करें। फिर क्रमिक रूप से निम्न कार्य करें:

अजगर virtualenv स्थापित करें;
एक नया आभासी वातावरण बनाएं और सक्रिय करें;
फ़ाइल में सूचीबद्ध सभी आवश्यक निर्भरता में इसे स्थापित करें
आवश्यकताएँ। txt, जो परियोजना रिपॉजिटरी की जड़ में संग्रहीत है।

 stage('Install Dependencies') { steps { sh ''' docker run --rm -i python:3.7 python3 -m pip install --user --upgrade pip python3 -m pip install --user virtualenv python3 -m virtualenv pyenv . pyenv/bin/activate pip install -r \${SPHINX\_DIR}/requirements.txt ''' } }

प्रलेखन के साथ एक साइट बनाएँ

अब एक साइट बनाते हैं। ऐसा करने के लिए, निम्नलिखित फ्लैग के साथ स्फिंक्स-बिल्ड कमांड चलाएं:

-q : लॉग चेतावनियां और त्रुटियां केवल;
-w : ध्वज के बाद निर्दिष्ट फ़ाइल के लिए एक लॉग लिखें;
-b : साइट बिल्डर का नाम;
-d : कैश्ड फ़ाइलों को संग्रहीत करने के लिए निर्देशिका निर्दिष्ट करें - doctree अचार।

असेंबली शुरू करने से पहले, rm -rf का उपयोग करके rm -rf पिछली साइट असेंबली और लॉग को हटा दें। चरणों में से एक पर त्रुटि के मामले में, स्पिनक्स-बिल्ड निष्पादन लॉग जेनकिंस कंसोल में दिखाई देगा।

 stage('Build') { steps { // clear out old files sh 'rm -rf ${BUILD_DIR}' sh 'rm -f ${SPHINX_DIR}/sphinx-build.log' sh ''' ${WORKSPACE}/pyenv/bin/sphinx-build -q -w ${SPHINX_DIR}/sphinx-build.log \ -b html \ -d ${BUILD_DIR}/doctrees ${SOURCE\_DIR} ${BUILD\_DIR} ''' } post { failure { sh 'cat ${SPHINX_DIR}sphinx-build.log' } } }

होस्ट साइट अपडेट

और अंत में, हम स्थानीय वातावरण में उपलब्ध उत्पाद दस्तावेज़ीकरण के साथ साइट को होस्ट करने वाली जानकारी को अपडेट करेंगे। वर्तमान कार्यान्वयन में, मेजबान वही आभासी मशीन है जो प्रलेखन को इकट्ठा करने और अद्यतन करने के कार्य के लिए जेनकिंस एजेंट के रूप में पंजीकृत है।

एक सिंक्रनाइज़ेशन टूल के रूप में, हम rsync उपयोगिता का उपयोग करते हैं। इसके लिए सही ढंग से काम करने के लिए, डॉकटर कंटेनर के बीच एक एसएसएच कनेक्शन को कॉन्फ़िगर करना आवश्यक है, जिसमें प्रलेखन के साथ साइट और मेजबान था।

Jenkinsfile का उपयोग करके SSH कनेक्शन को कॉन्फ़िगर करने के लिए, Jenkins में निम्न प्लगइन्स इंस्टॉल किए जाने चाहिए:

SSH Agent Plugin - आपको स्क्रिप्‍ट में उपयोग करने की अनुमति देता है।
SSH क्रेडेंशियल प्लगिन - आपको जेनकिंस सेटिंग्स में प्रपत्र उपयोगकर्ता नाम / कुंजी के क्रेडेंशियल्स को सहेजने की अनुमति देता है।

प्लगइन्स स्थापित करने के बाद, आपको क्रेडेंशियल अनुभाग में फ़ॉर्म भरकर मेजबान से कनेक्ट करने के लिए वर्तमान क्रेडेंशियल्स निर्दिष्ट करना होगा:

आईडी : पहचानकर्ता जिसका उपयोग विशिष्ट क्रेडेंशियल्स ( docs-deployer ) को इंगित करने के लिए sshgent कदम में जेनकिंसफाइल में किया जाएगा;
उपयोगकर्ता नाम : उपयोगकर्ता नाम जिसके तहत साइट डेटा अपडेट संचालन किया जाएगा (उपयोगकर्ता को होस्ट के /var/html फ़ोल्डर तक पहुंच लिखना होगा);
निजी कुंजी : मेजबान तक पहुंचने के लिए एक निजी कुंजी;
Passphrase : कुंजी के लिए पासवर्ड, अगर इसे जनरेशन स्टेज पर सेट किया गया था।

नीचे स्क्रिप्ट कोड है जो SSH के माध्यम से जुड़ता है और आवश्यक डेटा के लिए पथों के साथ पर्यावरण तैयार करने के चरण में निर्दिष्ट सिस्टम चर का उपयोग करके मेजबान पर जानकारी को अपडेट करता है। Rsync आदेश का परिणाम लॉग को लिखा जाता है, जो सिंक्रनाइज़ेशन त्रुटियों के मामले में जेनकिंस कंसोल में प्रदर्शित किया जाएगा।

 stage('Deploy') { steps { sshagent(credentials: ['docs-deployer']) { sh ''' #!/bin/bash rm -f ${SPHINX_DIR}/rsync.log RSYNCOPT=(-aze 'ssh -o StrictHostKeyChecking=no') rsync "${RSYNCOPT[@]}" \ --delete \ ${BUILD_DIR_CI} ${DEPLOY_HOST}/ ''' } } post { failure { sh 'cat ${SPHINX_DIR}/rsync.log' } } }

जेनकिंस और बिटबकेट एकीकरण

जेनकिंस और बिटबकैट के इंटरैक्शन को व्यवस्थित करने के कई तरीके हैं, लेकिन हमारी परियोजना में हमने जेनकिंस प्लगइन के लिए परिमाणित बिल्ड का उपयोग करने का निर्णय लिया। आधिकारिक दस्तावेज में प्लगइन को स्थापित करने के लिए विस्तृत निर्देश हैं , साथ ही सेटिंग्स जो दोनों प्रणालियों के लिए निर्दिष्ट की जानी चाहिए। इस प्लगइन के साथ काम करने के लिए, आपको जेनकिंस उपयोगकर्ता बनाने और उसके लिए एक विशेष टोकन बनाने की आवश्यकता है जो इस उपयोगकर्ता को सिस्टम में लॉग इन करने की अनुमति देगा।

एक उपयोगकर्ता और एपीआई टोकन बनाना

जेनकिंस में एक नया उपयोगकर्ता बनाने के लिए, जेनकिंस सेटिंग्स पर जाएं -> उपयोगकर्ता प्रबंधन -> उपयोगकर्ता बनाएं , और फ़ॉर्म में सभी आवश्यक क्रेडेंशियल्स भरें।

प्रमाणीकरण तंत्र जो तृतीय-पक्ष स्क्रिप्ट या एप्लिकेशन को जेनकिंस एपीआई का उपयोग करने की अनुमति देता है, वास्तव में उपयोगकर्ता पासवर्ड प्रसारित करने के लिए एक विशेष एपीआई टोकन है जो प्रत्येक जेनकिंस उपयोगकर्ता के लिए उत्पन्न किया जा सकता है। ऐसा करने के लिए:

पहले बनाए गए उपयोगकर्ता के विवरण का उपयोग करके प्रबंधन कंसोल में प्रवेश करें;
जेनकिंस कॉन्फ़िगर करने के लिए जाओ -> उपयोगकर्ता प्रबंधन ;
उपयोगकर्ता के नाम के दाईं ओर गियर आइकन पर क्लिक करें जिसके तहत वे सिस्टम में अधिकृत हैं;
मापदंडों की सूची में टोकन एपीआई खोजें और नए टोकन जोड़ें बटन पर क्लिक करें;
दिखाई देने वाले क्षेत्र में, एपीआई टोकन के पहचानकर्ता को निर्दिष्ट करें और जनरेट बटन पर क्लिक करें;
स्क्रीन पर प्रॉम्प्ट के बाद, जनरेट किए गए API टोकन को कॉपी और सेव करें।

अब Bitbucket सर्वर की सेटिंग में, आप डिफ़ॉल्ट उपयोगकर्ता को जेनकिंस से कनेक्ट करने के लिए निर्दिष्ट कर सकते हैं।

निष्कर्ष

यदि पहले की प्रक्रिया में कई चरण शामिल थे:

अद्यतन को रिपॉजिटरी में डाउनलोड करें
शुद्धता की पुष्टि के लिए प्रतीक्षा करें;
प्रलेखन के साथ एक वेबसाइट रखो;
होस्ट पर अद्यतन जानकारी;

अब बस Bitbucket में एक बटन मर्ज पर क्लिक करें। यदि जाँच के बाद स्रोत फ़ाइलों में परिवर्तन करने की आवश्यकता नहीं है, तो डेटा की शुद्धता की पुष्टि करने के तुरंत बाद प्रलेखन का वर्तमान संस्करण अपडेट किया जाता है।

यह तकनीकी लेखक के कार्य को बहुत सरल करता है, उसे बड़ी संख्या में मैन्युअल कार्यों से बचाता है, और परियोजना प्रबंधकों को प्रलेखन परिवर्धन और प्रतिक्रिया पर नज़र रखने के लिए एक सुविधाजनक उपकरण मिलता है।

इस प्रक्रिया को स्वचालित करना एक प्रलेखन प्रबंधन बुनियादी ढांचे के निर्माण में पहला कदम है। भविष्य में, हम स्वचालित परीक्षणों को जोड़ने की योजना बनाते हैं जो दस्तावेज़ में उपयोग किए गए बाहरी लिंक की शुद्धता की जांच करेंगे, और साथ ही इंटरेक्टिव इंटरफ़ेस ऑब्जेक्ट बनाना चाहते हैं जो स्फिंक्स के लिए तैयार थीम में बनाए गए हैं।

ध्यान से पढ़ने वालों के लिए धन्यवाद, जल्द ही हम अपनी परियोजना में प्रलेखन बनाने का विवरण साझा करना जारी रखेंगे!

कोड के रूप में डॉक्स। भाग 1: अद्यतन को स्वचालित करें