प्राकृतिक डॉक्स + गिटहब पेज = मुफ्त के लिए ऑनलाइन ऑटो-प्रलेखन (लगभग)

GitHub में GitHub Pages नामक एक मज़ेदार चीज़ है ।

इसका उपयोग दो तरीकों से किया जा सकता है - आप या तो साइट को हिला सकते हैं, या रिपॉजिटरी को डॉक बना सकते हैं, मैनुअल इसका विवरण देता है।

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

तो, हमें खुद NaturalDocs की जरूरत है - जाने, डाउनलोड, सेट, उदाहरण देखें।

इसके अलावा, हमें GitHub पर एक मानक नई परियोजना बनाने की आवश्यकता होगी। आप इसका पता लगाएंगे, हाँ कैसे। उदाहरण के लिए, इसे मेरा नया कूल प्रोजेक्ट कहते हैं (आप मौजूदा का उपयोग कर सकते हैं, लेकिन नई बिल्लियों पर प्रशिक्षण करना बेहतर है)।

इसे एक लंबे बॉक्स में डाले बिना, हम तुरंत पृष्ठों को फ्लिक करेंगे, कुछ इस तरह:

cd My-New-Cool-Project
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
echo "My GitHub Page" > index.html
git add .
git commit -a -m "First pages commit"
git push origin gh-pages

इस प्रक्रिया में मज़ेदार शिलालेख होंगे कि वहाँ कुछ हटा दिया गया है - यह सामान्य है :)

Http: // username .github.com / My-New-Cool-Project / पृष्ठ पर जाने का प्रयास करें, जहाँ हम आपका उपयोगकर्ता नाम उपयोगकर्ता नाम के बजाय रखते हैं।

सिद्धांत रूप में, हमें ऊपरी बाएँ कोने में शिलालेख "मेरा गिटहब पृष्ठ" के साथ एक खाली पृष्ठ मिलना चाहिए। वहाँ है महान, आगे बढ़ें।

कोड और दस्तावेज़ीकरण के साथ सौदा करते हैं।

सबसे पहले, जांचें कि हम मास्टर ब्रंच में कहां लौटेंगे

git status

यदि शुरुआत इस तरह से दिखती है

# On branch gh-pages

करना

git co master

ठीक है, अब मास्टर शाखा में प्रोजेक्ट फ़ोल्डर में, यह संरचना बनाएँ:

mkdir lib
mkdir doc
mkdir nd_internal

पहला हमारे कोड के लिए डायरेक्टरी है, दूसरा वह स्थान है जहाँ प्रलेखन जोड़ा जाएगा, नेचुरल डॉक्स के लिए अंतिम आवश्यक है

एनबी। इसे बनाने के बाद, nd_internal फ़ोल्डर को git के अंतर्गत से हटा दें। इसके बाद। init / info / oute फ़ाइल में एक नई लाइन जोड़ें nd_internal / *।

अब हम कुछ प्रकार के कोड लिख रहे हैं, इसके साथ नेचुरल डॉक्स स्टाइल (लिबास फोल्डर में) टिप्पणियों के साथ।

ठीक है, चलो हमारे पास टिप्पणियों के साथ कोड डालते हैं, हमें NaturalDocs को समझाने की ज़रूरत है कि हम क्या चाहते हैं। निम्नलिखित की तरह कुछ लिखने के लिए आवश्यक:

naturaldocs -i ./lib/ -o HTML ./doc/ -p ./nd_internal/

जहाँ पर naturaldocs आपके NaturalDocs के निष्पादन योग्य फ़ाइल का नाम है, यह ऊपर से भिन्न हो सकता है, आप इसका पता लगा लेंगे।

यदि सब कुछ ठीक रहा, तो आपको कुछ ऐसा दिखाई देगा:

Finding files and detecting changes...
Parsing 1 file...
Building 1 file...
Building 2 indexes...
Updating CSS file...
Done.

डॉक्टर निर्देशिका से index.html फ़ाइल खोलने का प्रयास करें - आपको प्रलेखन के साथ एक सुंदर पृष्ठ मिलना चाहिए।

अब हम सभी परिवर्तन करते हैं, लेकिन हम अभी तक कुछ भी धक्का नहीं देते हैं (यदि डॉक उत्पन्न किए गए थे और साइट पर कुछ भी नहीं बदला है, तो हम अगले चरण से पहले प्रतिबद्ध करना भूल गए)।

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

#!/bin/bash

doc_dir='doc' # document directory
tmp_message='tmp_mess' # temporary files for changelog message
gh_pages='refs/heads/gh-pages' # refs to pages

parent_sha=$(git show-ref -s $gh_pages)
doc_sha=$(git ls-tree -d HEAD $doc_dir | awk '{print $3}')
git log --pretty=format:'%s' -n 1 $doc_dir > $tmp_message
new_commit=$(git commit-tree $doc_sha -p $parent_sha < $tmp_message )
rm $tmp_message
git update-ref $gh_pages $new_commit

echo "Docs update done"

सिद्धांत रूप में, सबकुछ ठीक होना चाहिए था और हमें जीएच-पन्नों की शाखा में दस्तावेजों का अद्यतन प्राप्त हुआ।

अब करने का समय है

git push

जवाब में, हमें कुछ ऐसा मिलना चाहिए:

Counting objects: 24, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (12/12), done.
Writing objects: 100% (13/13), 1.26 KiB, done.
Total 13 (delta 5), reused 0 (delta 0)
To git@github.com:Meettya/My-New-Cool-Project.git
f0005ad..a53b950 gh-pages -> gh-pages
48b901d..f0b787e master -> master

इसमें महत्वपूर्ण बात यह है कि अंतिम दो लाइनें हैं, दोनों शाखाओं में दो कमिट होनी चाहिए।

और अब हम http: // username .github.com / My-New-Cool-Project / पर जाते हैं और जाँचते हैं कि सबकुछ ठीक है या नहीं। सिद्धांत रूप में, हमें अपने अद्भुत प्रलेखन को देखना चाहिए।

अब, कुछ भी हमें README फाइल में हमारे डॉक का लिंक बनाने और कोड के स्वचालित प्रलेखन से लाभ प्राप्त करने से रोकता है।

मेरा परीक्षण प्रोजेक्ट, जिसे कैसे और क्या किया गया है, इस विषय पर घुमाया जा सकता है - jQuery एन्हांस लाइब्रेरी । वहाँ आप डॉक्स और सभी लिपियों के उदाहरण के साथ-साथ नेचुरल डॉक्स सिंटैक्स का उदाहरण पा सकते हैं।