एक लंबे समय के लिए, कई लोग सक्रिय रूप से या सक्रिय रूप से कोडिंग के रूप में भंडारण और प्रकाशन के मॉडल का उपयोग कर रहे हैं या देख रहे हैं, इसका मतलब है
कि कोड के समान नियम, उपकरण और प्रक्रिया को प्रोग्राम कोड पर लागू करना, उदाहरण के लिए, इसे भंडार में संग्रहित करना, परीक्षण चलाना, संकलन और जारी करना। CI / सीडी में। यह दृष्टिकोण आपको परिचित विकास उपकरणों का उपयोग करके कोड, संस्करण और ट्रैक परिवर्तनों के साथ प्रलेखन को अद्यतित रखने की अनुमति देता है।
हालांकि, एक ही समय में, कई कंपनियों ने भी वर्षों तक विकीज़ किया है, जिसमें अन्य टीमों और कर्मचारियों, उदाहरण के लिए, परियोजना प्रबंधकों के पास प्रलेखन तक पहुंच है। यदि आप संग्रहण और प्रकाशन को एक दृश्य में लाना चाहते हैं, तो यह है कि HTML के साथ साथ कंफ्लुएंस में डॉक प्रकाशित करें? इस लेख में मैं कॉन्फ्लुएंस में भंडार से दस्तावेजों को प्रकाशित करने के कार्य के लिए समाधानों का अवलोकन दूंगा।
मैं इंटरफ़ेस डेवलपमेंट टीम (RST-Sphinx + sphinxcontribbuilder बंडल) में लंबे समय से एक समाधान
का सक्रिय रूप से
उपयोग कर रहा हूं, और मैं दूसरों को एक विकल्प के रूप में प्रस्तुत करूंगा, मैं तुरंत एक आरक्षण कर दूंगा कि व्यवहार में मैंने उन्हें नहीं आज़माया, मैंने अभी कॉन्फ़िगरेशन का अध्ययन किया है।
स्फिंक्स डॉक्टर + स्फिंक्स कॉन्ट्रिब्युलर
स्फिंक्स (एक ही नाम के खोज सूचकांक के साथ भ्रमित नहीं होना) पायथन में लिखा गया एक प्रलेखन जनरेटर है और समुदाय द्वारा सक्रिय रूप से उपयोग किया जाता है, यह अन्य वातावरण में भी काफी अच्छी तरह से काम करता है।
हम इसे विस्तार से स्थापित करने पर ध्यान केंद्रित नहीं करते हैं, मैं केवल एक आरक्षण करूंगा कि यह बॉक्स से बाहर स्थिर HTML, मैन, पीडीएफ और कई अन्य स्वरूपों को उत्पन्न कर सकता है, और रिपॉजिटरी में सही असेंबली और प्रकाशन के लिए अनुक्रमणिका फ़ाइलें (मुख्य पृष्ठ का लेआउट) होनी चाहिए। conf.py (कॉन्फ़िगरेशन फ़ाइल) और मेकफाइल (एक फ़ाइल जो स्वरूपों को बनाने की प्रक्रिया का वर्णन करती है, यहां इसे docker में सीवे करना और वहां
स्फिंक्स-बिल्ड कमांड चलाना संभव है)।
बॉक्स से बाहर, स्फिंक्स हल्के * .rst (RestructuredText) लेआउट से डॉक उत्पन्न कर सकता है, लेकिन हमने उन डेवलपर्स के लिए मार्कडाउन (कॉमनमार्क फ्लेवर) में लिखने की क्षमता को जोड़ा जो अधिक आरामदायक हैं (
एम 2 आर एक्सटेंशन एमडी को आरएसटी में परिवर्तित करता है)। ।
हमने स्फिंक्स के लिए पहले से ही पूरा वातावरण स्थापित किया है, और प्रलेखन विधानसभा को जेनकिंस
पाइपलाइन में एक अलग चरण में वायर्ड किया गया है, इसलिए हमने आगे बढ़कर
sphinxcontrib.confluencebuilder एक्सटेंशन का उपयोग किया, जो
कॉन्फ्लुएंस के लिए मूल प्रारूप में एकत्र कर सकते हैं और फिर उन्हें प्रकाशित कर सकते हैं। इस मामले में संगम HTML के साथ प्रलेखन आउटपुट स्वरूपों में से एक है।
इसे काम करने के लिए, आपको एक्सटेंशन को conf.py में कनेक्ट करना होगा, नीचे कॉन्फ़िगरेशन टुकड़ा है।
extensions = [ 'sphinxcontrib.confluencebuilder', 'm2r' ] templates_path = ['_templates'] source_suffix = ['.rst', '.md'] master_doc = 'index' exclude_patterns = [ u'docs/warning-plate.rst', u'FEATURE.md', u'CHANGELOG.md', u'builder/README.md' ]
और फिर एक्सटेंशन कॉन्फ़िगर करें, इसमें सेटिंग्स का एक सेट है:
confluence_publish = True
महत्वपूर्ण बिंदु यह है कि भले ही पृष्ठ (.rst में स्रोत) toc में निर्दिष्ट नहीं है और इसे बाहर करने के लिए जोड़ा नहीं गया है, इसे अभी भी प्रकाशित किया जाएगा, लेकिन पदानुक्रम के बाहर।
Confluence के पृष्ठों के नाम, पृष्ठ के पहले शीर्षक के अनुरूप होंगे, उदाहरण के लिए, यदि आपके पास example.rst फ़ाइल में उदाहरण शीर्षक है, तो समान संकेतों के साथ रेखांकित, यह Confluence में पृष्ठ का नाम बन जाएगा।
स्वच्छता नियम, जो बहुत स्पष्ट है, लेकिन फिर भी: प्राधिकरण डेटा के साथ एक बॉट बनाएं, जिसके लिए आप दस्तावेजों को प्रकाशित करेंगे, उन्हें पाइपलाइन में उपयोग किए जाने वाले डॉक रचना में पर्यावरण चर के रूप में स्थानांतरित किया जा सकता है।
बेशक, नुकसान हैं। सबसे पहले, Confluence (□ °） ° ┻━┻ this R) में प्रकाशन के लिए सभी RST सिंटैक्स का समर्थन नहीं किया जाता है, यदि आप HTML और Confluence को एक स्रोत से एकत्रित करना चाहते हैं तो यह असुविधाजनक है। कंटेनर, हाईलिस्ट निर्देशों का समर्थन नहीं किया जाता है, लगभग सभी निर्देशकीय विशेषताओं, उदाहरण के लिए, ब्लॉक कोड में लाइनों को हाइलाइट करना, सामग्री की तालिका में नंबरिंग, सूची के लिए संरेखित और चौड़ाई।
जो समर्थित है उसकी सूची बहुत अच्छी है ।
सुखद लोगों में से, समर्थित हैं, यह आपको विभिन्न दस्तावेजों के बीच सामग्री के टुकड़ों का पुन: उपयोग करने की अनुमति देता है, कोड से दस्तावेज़ीकरण कोड के लिए ऑटोडोक, गणितीय सूत्रों के लिए गणित, टिकट से ड्राइंग और जीरा से फिल्टर (इसके लिए आपको कॉन्फ़िगरेशन में जीरा सर्वर को पंजीकृत करने की भी आवश्यकता होगी), हेडर और बहुत कुछ। एक और, सचमुच 3 जनवरी को एक
बड़ा अद्यतन फेंक दिया।
वैसे, पंडॉक मल्टीकॉन्सर में जीरा सपोर्ट दिखाई दिया,
संस्करण 2.7.3 से शुरू होकर
पंडोक ने इसी संगम स्थल मार्कअप का समर्थन किया।
उन मैक्रोज़ और कॉन्फ्लुएंस तत्वों के लिए जो समर्थित नहीं हैं, एक गंदा हैक है। RST का एक निर्देश है
... कच्चा :: , और इसमें एक संगम विशेषता है, यह conf markup को स्वीकार करता है, यदि आपको वास्तव में किसी प्रकार के मैक्रो की आवश्यकता है - आप इसे Confluence में पृष्ठ संपादन मोड में कॉपी कर सकते हैं (स्रोत कोड मोड <> आइकन द्वारा उपलब्ध है) और वहां अपना "कच्चा" कोड चिपकाएँ। लेकिन मैंने आपको यह नहीं सिखाया।
.. raw:: confluence <ac:structured-macro ac:macro-id="c38bab13-b51e-4129-85ef-737eab8a1c47" ac:name="status" ac:schema-version=^_^quot quot^_^> <ac:parameter ac:name="colour">Green</ac:parameter> <ac:parameter ac:name="title">Is used</ac:parameter> </ac:structured-macro>
परिणाम इस प्रकार है:
हमें स्थानीय रिपॉजिटरी से परीक्षण पृष्ठ पर प्रकाशन को कॉन्फ़िगर करने की आवश्यकता क्यों थी, और तुरंत "ठेस" पर नहीं? तथ्य यह है कि जब आप सभी पृष्ठों को प्रकाशित करते हैं तो हर बार फिर से प्रकाशित होते हैं और मैन्युअल रूप से किए गए बदलाव या लाइन (इनलाइन) में टिप्पणियों को पीसते हैं। इसलिए, जब दस्तावेज़ प्रगति पर है, तो हमने समीक्षा और प्रकाशित टिप्पणियों को एकत्र करने के लिए एक अलग पेज, जैसे कि देव मोड में प्रकाशित करने का फैसला किया।
CI में, प्रकाशन को जेनकिंस पाइपलाइन में एक अलग चरण के रूप में लागू किया जाता है, इस चरण के अंदर दूरस्थ रजिस्ट्री पर docker छवि लॉन्च की जाती है, जो वांछित कॉन्फ़िगरेशन के साथ स्फिंक्स-बिल्ड को लागू करती है। इस कदम को तुरंत छोड़ देना बेहतर है।
pipeline { agent { label "${AGENT_LABEL}" } stage("Documentation") { steps { ansiColor('xterm') { withCredentials([usernamePassword( credentialsId: "${DOCUMENTATION_BOT}", usernameVariable: 'CONFLUENCE_USERNAME', passwordVariable: 'CONFLUENCE_PASSWORD' )]) { sh "docker-compose -p $COMPOSE_ID run sphinx-doc confluence" } }} }
मंच के अंदर,
डॉकटर-कम्पोज़-पी रिलीज़-ब्रांच-नेम रन स्फिंक्स-डॉक संगम वास्तव में लॉन्च किया गया है। जेनकिंसफाइल, बदले में, निर्भरता और पर्यावरण का वर्णन करता है जिसमें कदम उठाया जाएगा, लक्ष्य में जानकारी को इकट्ठा करने और अद्यतन करने की प्रक्रिया। परीक्षणों से अब तक .md और .rst के साथ doc8 और markdownlinter की केवल एक वाक्यविन्यास जाँच होती है।
एक और बारीकियों: हर बार जब आप एक पृष्ठ सबनेट प्रकाशित करते हैं, तो स्फिंक्स पूरे पेड़, प्रत्येक पृष्ठ को अपडेट करता है। यही है, भले ही सामग्री में बदलाव न हुआ हो, एक परिवर्तन किया जाता है, यदि आपके पास चैनल में सूचनाओं को कॉन्फ़िगर किया गया है, तो यह बहुत सारी सूचनाओं से भरा हो जाएगा।
कुछ और तरीके
बैकएंड के रूप में कॉन्फ्लुएंस के साथ फोलिएंट
Mkdocs और कई पूर्वप्रक्रमकों के साथ हुड के नीचे और कान्फ्लुएंस के रूप में बैकेंड के साथ फर्जी प्रलेखन उपकरण। आप
यहां और अधिक पढ़ सकते हैं , लेकिन संक्षेप में, यह एमडी को HTML में बदलने के लिए पैंडॉक का उपयोग करता है, और फिर इसे कॉन्फ्लुएंस में प्रकाशित करता है। आपको केवल बैकएंड को कॉन्फ़िगर करने और वातावरण में एक निर्भरता के रूप में पैंडॉक स्थापित करने की आवश्यकता है।
पहले समाधान से अनुकूल अंतर: यह उन्हीं स्थानों पर इनलाइन टिप्पणियों को पुनर्स्थापित कर सकता है, जो वे पृष्ठ प्रकाशित होने से पहले थीं, आप उन्हें कॉन्फ़िगर करके पृष्ठ बनाने, उनके नाम संपादित करने और मौजूदा पृष्ठ में सामग्री डालने की अनुमति देते हैं, इसके लिए आपको मैन्युअल रूप से सेट करने की आवश्यकता होती है संगम पर पृष्ठ पर मूर्धन्य लंगर।
यह केवल Markdown पर स्रोत के साथ काम करता है।
मेट्रो
एक मल्टीटूल जो Google डॉक्स से लेकर सेल्सफोर्स क्विप तक और मार्कडाउन में भी कंफ्यूजन में कई तरह के सोर्स फॉर्मेट प्रकाशित करता है।
प्रकाशित करने के लिए, आपको अपनी .md फ़ाइलों को फ़ोल्डर में मैनिफ़ेस्ट.जॉसन फ़ाइल में रखने की आवश्यकता है, जहाँ उस फ़ोल्डर को निर्दिष्ट करें, जिस फ़ाइल को आप प्रकाशित करना चाहते हैं, प्रत्येक फ़ाइल के लिए संगम पृष्ठ आईडी निर्दिष्ट करें। पृष्ठ का शीर्षक फ़ाइल (#) में पहला शीर्षक होगा। इस उपकरण में मार्कडाउन मार्कअप के साथ कुछ विकृतियां हैं, इसलिए
डॉक्स देखें । अनुलग्नक और चित्रों को एक ही फ़ोल्डर में रखने की आवश्यकता होती है, और उपकरण आपको सामग्री की तालिका का उपयोग सीधे कॉन्फ़िगरेशन में निर्दिष्ट करने की अनुमति देता है।
मणि md2conf
माणिक रत्न
md2conf , यह
मार्कडाउन को कनफ्लुएंस एक्सएचटीएमएल के लिए देशी में परिवर्तित करता है। फिर आप रेक कार्य लिख सकते हैं, जो मास्टर को पुश करने के लिए गिटलैब सीआई / जेनकिंस के माध्यम से कॉल किया जा सकता है, फिर पृष्ठ को प्रकाशित करने के लिए कॉन्फ्लुएंस एपीआई को खींचें। रूबी पर्यावरण को आपके पास नहीं लाने के लिए, एक कंटेनर में इस मणि के लिए निर्भरता को लपेटें।
कंफ्लुएंस एपीआई के लिए अनुरोध भेजने का तरीका
यहां बताया गया
है ।
यह केवल Markdown पर स्रोत के साथ काम करता है।
गितुब पर पाया
वास्तव में, इस तरह की कई स्क्रिप्ट या क्ली-टूल्स समुदाय में पहले ही किए जा चुके हैं, लेकिन मैंने केवल md2conf के साथ प्रयोग किया है, वे सभी दो समूहों में विभाजित हैं।
वे जो केवल स्वरूपों को परिवर्तित करते हैं (md, asciidoc, rst -> संगम / xhtml):उनमें से सबसे अधिक विचारशील है जो मैंने देखा है यह एक है (https://github.com/rogerwelin/markdown2confluence-server), लेखक ने तुरंत डॉकरफाइल लिखा, जो आरआईएस सर्वर के रूप में क्ली-टूल को उठाता है, फिर आप इसे रूपांतरण अनुरोधों का एक पैकेट भेज सकते हैं। ।
और जो लोग तुरंत अपने आप
को कॉन्फ्लुएंस एपीआई के अनुरोधों को लागू करते हैं , आपको केवल एपीआई में एपीआई कुंजी निर्दिष्ट करने की आवश्यकता है:
कोई भी विकल्प चुनें (अपनी मार्कअप भाषा और स्टैक पर निर्भर करता है) और अपने कार्यों का सामना करने वाले कार्यों के आधार पर अपनी पाइपलाइन इकट्ठा करें।
PS यदि आप टिप्पणियों में समस्या के अन्य पाए गए समाधानों को साझा करते हैं, तो मैं बहुत आभारी रहूंगा।
और अगर आप मेरे साथ इन विषयों पर अधिक बात करना चाहते हैं, तो 18 मई को नॉलेजकोन 2020 पर आएं।