मैं गिटहब पेज

Question

के लिए जावास्क्रिप्ट एपीआई दस्तावेज कैसे उत्पन्न कर सकता हूं अन्य भाषाओं के लिए एपीआई दस्तावेज उत्पन्न करने के लिए बहुत सारे विकल्प हैं, लेकिन मुझे अभी तक अपने जावास्क्रिप्ट एपीआई के लिए कोई समाधान नहीं मिला है जिसे मैं गिटहब पेज पर होस्ट करना चाहता हूं। ऐसा लगता है कि मैं JSDoc3 का उपयोग कर सकता हूं लेकिन मुझे एक कस्टम प्लगइन बनाने की आवश्यकता होगी जो जैकेल मार्कअप आउटपुट करे।

मैं कोड यूआरएल को गिटहब से लिंक करने के लिए भी पसंद करूंगा। मुझे jsdoc-githubify मिला जो लिंक को बदलने के लिए आउटपुट को बंद कर देगा, लेकिन मैं अधिक सरल विकल्प पसंद करूंगा जहां मेरे पास अधिक नियंत्रण होगा।

क्या मुझे अपना स्वयं का जेएसडीओसी प्लगइन बनाना है, या वहां कोई बेहतर समाधान है जिसे मैंने याद किया है। इसके लिए लोग क्या उपयोग करते हैं?

Answer 1

मुझे लगता है कि यह आपके लिए क्या देख रहे है: http://jsdox.org/

jsdox एक सरल jsdoc 3 जनरेटर है। यह आपके जावास्क्रिप्ट फ़ाइलों से jsdoc 3 के उप-समूह के आधार पर प्रलेखन टैग खींचता है और मार्कडाउन फ़ाइलों को उत्पन्न करता है।

Answer 2

आप Grunt से परिचित हैं, तो आप आसानी grunt-jsdoc साथ .html डॉक्स उत्पन्न कर सकते हैं।

• JSDoc के साथ अपना कोड दस्तावेज़।
• grunt-jsdoc का उपयोग करें जो कोड प्रलेखन उत्पन्न करने के लिए आंतरिक रूप से jsdoc का उपयोग करता है।
• यह HTML में स्रोत कोड भी आउटपुट करेगा और दस्तावेज़ीकरण के भीतर इसमें प्रत्येक सार्वजनिक रूप से सुलभ सदस्य के लिए कोड लाइनों के लिंक शामिल होंगे।
• तुम भी बस JSDoc की @link निर्देश का उपयोग करके लिंक पर नियंत्रण हो सकता है:
  See {@link https://github.com/onury|My GitHub Profile}।

नीचे एक ग्रंटफाइल उदाहरण देखें।
ध्यान दें कि यह सभी JSDoc CLI options का समर्थन करता है।

grunt.initConfig({ 
    'jsdoc': { 
     dist: { 
      src: ['./src/core/mylib.js'], 
      options: { 
       destination: './doc/html' 
      } 
     } 
    } 
}); 

और आप इस कार्य को grunt jsdoc के साथ चलाते हैं। या जब भी फ़ाइल बदलती है, तो आप grunt-contrib-watch प्लगइन को स्वचालित रूप से चलाने के लिए जोड़ सकते हैं।

टेम्पलेट्स और स्टाइलिंग:

• तुम हमेशा सीएसएस फ़ाइल के साथ खेलते हैं और अपने खुद के स्वाद के लिए इसे अधिलेखित कर सकते हैं।
• या आप बूटस्ट्रैप पर आधारित JSDoc3 के लिए docstrap टेम्पलेट का उपयोग कर सकते हैं जिसका उपयोग grunt-jsdoc के साथ किया जा सकता है।

का उपयोग Jekyll प्रलेखन के लिए:

हालांकि यह मूल रूप से समर्थित है, तो आप GitHub पेज के लिए Jekyll उपयोग करने के लिए नहीं है। जैकिल वास्तव में स्थिर वेबसाइटों या ब्लॉगों के लिए डिज़ाइन किया गया है। लेकिन यह मार्कडाउन फाइलें ले सकता है।इसलिए, मैं पहले jsdoc-to-markdown के माध्यम से कोड से जिथब स्वादयुक्त मार्कडाउन फाइलें बनाउंगा (इसके अलावा एक ग्रंट प्लगइन grunt-jsdoc2md भी है) तो configure तदनुसार एक जैकिल प्रोजेक्ट।

लेकिन ध्यान दें कि आपको जेकिल को स्थापित और कॉन्फ़िगर करने के लिए कुछ अतिरिक्त कार्य करने की आवश्यकता होगी। यहां से शुरू करने के लिए एक अच्छा article और sample project है।

अद्यतन:

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

कुंजी डोक्मा विशेषताएं हैं; यह दोनों JSDoc और मार्कडाउन फ़ाइलों को HTML दस्तावेज़ में फ़ाइलों को उत्पन्न करता है, एक वेब-ऐप उत्पन्न करता है, बेहद विन्यास योग्य और गीथब पेज के साथ बढ़िया काम करता है।

Docma documentation here देखें, जो डोक्मा के साथ भी बनाया गया है और गिटहब पेज पर होस्ट किया गया है।

Answer 3

हालांकि मैं एक समय में यह अद्यतन नहीं किया है, https://github.com/punkave/dox-foundation एक और विकल्प है:

Docma का एक नमूना स्क्रीनशॉट एसपीए उत्पन्न। यह सिर्फ HTML फ़ाइलों को उत्पन्न करेगा जो आप अपने gh-pages शाखा में प्रतिबद्ध कर सकते हैं।

Answer 4

मैं स्वैगर का प्रशंसक हूं: https://github.com/swagger-api/swagger-ui & http://swagger.io/।

इसमें केवल एपीआई दस्तावेज से अधिक शामिल है, इसलिए हो सकता है कि यह आपके लिए अधिक हो, लेकिन यह एपीआई दस्तावेज करने का एक सुंदर काम करता है।

Answer 5

JSDox वही है जो आप खोज रहे हैं।

Answer 6

API दस्तावेज़ों कि Jekyll मार्कअप आउटपुट पैदा करने को आसान बनाने की यह

• GitHub पन्नों में कोशिश कर रहा।

  {% raw %} टैग के साथ तरल टेम्पलेट से बचें।

  {% raw %} 
      I want to be {{escaped}}. 
  {% endraw %} 
  

  रेफरी: GitHub/.com/Shopify/तरल/wiki/तरल के लिए डिजाइनर # कच्चे

  रेफरी: jekyllrb/.com/docs/GitHub-पृष्ठों/# परियोजना पृष्ठों

  दो शाखाएं बनाएं, एक gh-pages के लिए मास्टर एक के लिए, मास्टर शाखा में आपकी .md फ़ाइल होती है और gh-pages में स्थिर जेनरेट की गई .html फ़ाइल होती है। स्थानीय कंप्यूटर में: $ jekyll build वर्तमान प्रोजेक्ट फ़ोल्डर में ./_site में उत्पन्न किया जाएगा।

  गिटहब पर अपलोड करें।

  Jekyll

  • मास्टर शाखा: GitHub/.com/Jekyll/Jekyll
  • gh-पृष्ठों शाखा: GitHub/.com/Jekyll/Jekyll/पेड़/gh-पृष्ठों

  अमेरिकन प्लान/प्रतिक्रिया

  • मास्टर शाखा: GitHub/.com/फेसबुक/प्रतिक्रिया/संपादित करें/मास्टर/docs/डॉक्स/रेफरी-01-टॉप -level-api.md
  • gh-पृष्ठों शाखा: GitHub/.com/फेसबुक/प्रतिक्रिया/ब्लॉब/gh-पृष्ठों/docs/उच्च-स्तरीय-api.html

पेज यूआरएल गिटहब दस्तावेज़ से खुद ही जुड़ा हुआ है।

_layouts फ़ोल्डर (एचटीएमएल टेम्पलेट) में लिंक "Edit on GitHub" on docs pages जोड़े यह है blog post about it