Aspnetcore: ASP.NET 5 दस्तावेज़ीकरण के लिए हमें किस प्रारूप का उपयोग करना चाहिए?

http://shfb.codeplex.com

या बस कुछ नया बनाएं।

जीएच मार्कडाउन उत्पन्न करने वाला एक अच्छा प्री-प्रोसेसर उत्कृष्ट होगा।

मार्कडाउन (या गिटहब फ्लेवर्ड मार्कडाउन) के लिए +1। इसमें कुछ विशेषताओं की कमी हो सकती है लेकिन यह बहुत प्रसिद्ध है और सीखने और उपयोग करने में बहुत आसान है। मुझे लगता है कि यह अंतिम निर्णय पर निर्भर हो सकता है कि इसे कहाँ होस्ट किया जाएगा, जैसा कि आपने कुछ विकल्पों का उल्लेख किया है।

हाय डैनियल,
आपके आपके योगदान हेतु धन्यवाद।
एक जूनियर देव के रूप में, मुझे लगता है कि साइडबार में शीर्षक के रूप में दस्तावेज़ को व्यवस्थित करना आसान है, इसी तरह http://rustbyexample.com/
(IMHO)

-1 कुछ नया बनाने पर।
+1 मौजूदा किसी चीज़ पर काम करने और यदि संभव हो तो बढ़ाने के लिए।

@ danroth27 क्या आप अपने दस्तावेज़ीकरण की ज़रूरतों के बारे में कुछ और विवरण साझा कर सकते हैं और एक परिपक्व दस्तावेज़ीकरण प्रणाली की आपको किन विशेषताओं की आवश्यकता है?

मुझे लगता है कि "मार्कडाउन का उपयोग करें" कहना बहुत सरल है।

मार्कडाउन एचटीएमएल के लिए एक डीएसएल है। बस इतना ही। क्या आप वाकई कहेंगे "दस्तावेज़ एक हल की गई समस्या है, आइए HTML का उपयोग करें!"

हमें स्फिंक्स जैसी वास्तविक दस्तावेज़ीकरण प्रणाली की आवश्यकता है।

• मार्कडाउन एक टीओसी उत्पन्न नहीं कर सकता।
• मार्कडाउन विषयों के बीच लिंक नहीं कर सकता (आपको मैन्युअल रूप से लिंक करना होगा)
• मार्कडाउन बहुभाषी समर्थन या बहु-संस्करण समर्थन जैसी चीजें नहीं कर सकता।

मैं @ericholscher के 'रीड द डॉक्स' का समर्थन करता हूं, लेकिन विशेष रूप से स्फिंक्स और रीस्ट्रक्चर्ड टेक्स्ट का।

या Doxygen का उपयोग करें और vNext कभी जारी नहीं किया जाएगा;)

रोसलिन या एंगुलरजेएस के समान कुछ के बारे में क्या? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

मार्कडाउन गिटहब पर अधिकांश अन्य परियोजनाओं के लिए बहुत अच्छा काम करता है। मार्कडाउन के लिए +1।

@shanselman , सापेक्ष लिंक?

मुझे लगता है कि स्फिंक्स का उपयोग करना काम करेगा।
@issafram उदाहरण यहाँ:
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger हम कुछ ऐसा चाहते हैं जिससे हम आसानी से सामग्री की तालिका तैयार कर सकें और आसानी से पृष्ठों में लिंक कर सकें। हम कुछ ऐसा भी चाहते हैं जो HTML, PDF और ePub सहित विभिन्न प्रकार के दस्तावेज़ स्वरूप उत्पन्न कर सके। दस्तावेज़ मोबाइल उपकरणों पर भी पढ़ने योग्य होने चाहिए।

@issafram मार्कडाउन बहुत अच्छा है जब आपके दस्तावेज़ सौ पृष्ठ हैं, सबसे अधिक संभावना कम है। लेकिन हजारों पेज और इंटरलॉकिंग टेबल ऑफ कंटेंट? अप टू डेट रख रहे हैं? ASP.NET और .NET दस्तावेज़ों को लिंक करना? गड़बड़ हो जाएगी।

ध्यान रखें, यदि आप चाहते हैं कि यह वास्तव में खुला स्रोत हो, और इस प्रकार कुछ ऐसा जो योगदान को प्रोत्साहित करे, तो यह प्रणाली यथासंभव सरल होनी चाहिए, जिसमें कोई सीखने की अवस्था न हो। मार्कडाउन अपने आप में एक टीओसी उत्पन्न नहीं कर सकता है, लेकिन अपेक्षाकृत सरल कोड मार्कडाउन से टीओसी उत्पन्न कर सकता है।
ऑर्चर्ड में हम अपने सिस्टम से बहुत खुश हैं, जो कि जीथब पर मार्कडाउन है और बहुत कम कोड वाली एक एज़्योर साइट है (ल्यूसीन इंडेक्सिंग और सर्चिंग, प्लस टीओसी पीढ़ी के लिए) जो हर बार रेपो को धक्का देने पर ऑटो-अपडेट हो जाती है। सुपर-सरल, परिचित उपकरण।
केवल एक चीज जो मुझे इसके बारे में पसंद नहीं है, वह है मेटाडेटा की कमी (हम फ़ाइल नामों से शीर्षक निकालते हैं), लेकिन इसके लिए भी समाधान हैं, जैसे कि जैकिल के YAML हेडर (गीथब द्वारा समर्थित) या मेरा अपना स्निपेबल प्रारूप।

@issafram उदाहरण के लिए बहुत सारे दस्तावेज़ों और रिफैक्टरिंग के साथ विशाल कोडबेस पर अच्छा काम नहीं करता है। एक वर्ग का नाम बदलें और _byeby_ सापेक्ष लिंक।

_edit_: मुझे खेल में देर हो रही है :P

मुझे यह जानकर प्रसन्नता हुई कि ASP.NET दस्तावेज़ीकरण हज़ारों पृष्ठों का होगा;) फिर भी, KISS।

@bleroy इस http://read-the-docs.readthedocs.org/en/latest/ और इसे बनाने वाले rST पर एक नज़र डालें। https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

ज़रूर, यह बहुत अच्छा है। बस अपना अनुभव दे रहे हैं। मैं समझता हूं कि आप एक अलग पैमाने पर हैं।

आरएसटी यहां सबसे अच्छा विकल्प है, हाथ। यह ASP.NET होने के नाते, कुछ ऐसा होना जो अपने इंडेक्स को अपडेट करने के लिए पर्याप्त स्मार्ट हो (ToC या यहां तक ​​कि एक क्लास लिस्टिंग के दृष्टिकोण से) शायद एक सर्वोच्च प्राथमिकता है।

आदर्श रूप से मैं उन सभी .XML फ़ाइलों को बायनेरिज़ से प्राप्त करने के लिए बिल्ड वर्कफ़्लो में कुछ चलाऊंगा और फिर उन्हें एक प्रोसेसर के माध्यम से उन फ़ाइलों को उत्पन्न करने के लिए रखूंगा जो फिर एक सर्वर पर प्रकाशित हो जाती हैं। सटीक टूलींग.... मुझे कोई जानकारी नहीं है। बहुतों का उल्लेख किया गया है। मैं आपको अपना खुद का और ओपन सोर्स बनाने की सलाह दूंगा। हां हां... बिल्ड बनाम बाय डिबेट लेकिन मुझे उन टूल्स का उपयोग करने से नफरत है जिनमें उपरोक्त में से कुछ जैसे अप्रबंधित संसाधन हैं। वैसे भी यह आदर्श लगता है ... आपके पास शायद बजट और समय की कमी है और क्या नहीं।

@issafram यदि आप सभी स्फिंक्स/आरटीडी का उपयोग कर रहे हैं, तो ब्रीद की तर्ज पर कुछ काम करने योग्य दृष्टिकोण हो सकता है: http://breathe.readthedocs.org/en/latest/ - यह स्फिंक्स और डॉक्सिजन के साथ एकीकरण है जो उपयोग करता है डॉक्सिजन एक्सएमएल फाइलें।

@issafram मुझे लगता है कि आप एसएचएफबी का वर्णन कर रहे हैं ... (वास्तव में सैंडकैसल , एसएचएफबी बस इसे उपयोग करने के लिए और अधिक सुखद बनाता है: पी)

हां, आपको प्रीप्रोसेसर/पोस्टप्रोसेसर की आवश्यकता है, आप टीओसी के लिए जीएचएमडी के साथ दस्तावेज़ के भीतर सापेक्षता को लिंक कर सकते हैं। हमारी परियोजनाओं के लिए हमने मूल रूप से .Net doc XML और कन्वेंशन आधारित नमूना कोड और एमडी में लिखी अन्य स्थिर सामग्री के साथ विलय किया। अंतिम परिणाम HTML है।

एमडी में कोड और संपादकीय स्थिर सामग्री होने से पीआर करना आसान हो जाएगा। स्रोत प्रारूप के रूप में मार्कडाउन के बारे में मुझे जो पसंद है वह यह है कि यह एचटीएमएल, एक्सएमएल इत्यादि की तुलना में क्लीनर आवंटित करता है। ऑडिटिंग को आसान और स्रोत नियंत्रण के लिए उपयुक्त बनाता है।

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

परियोजनाओं में रखरखाव और जोड़ने के लिए। Intersphinx एक अर्थपूर्ण तरीके से ऐसा करने का एक शक्तिशाली तरीका है। यह आपको सभी संदर्भों को सूचीबद्ध करने की अनुमति देता है (चाहे वे कोड या गद्य हों) और उन्हें परियोजनाओं में स्पष्ट रूप से लिंक करें।

यहां डॉक्स: http://sphinx-doc.org/latest/ext/intersphinx.html

यह उस तरह की कार्यक्षमता है जिसके बारे में मुझे पता है कि मार्कडाउन जैसी कोई चीज किसी भी तरह से नहीं है।

सहमत हूं कि मार्कडाउन सबसे अच्छा समाधान नहीं है, लेकिन अभी के लिए हमें एक सरल समाधान की आवश्यकता है। चलो हम डेवलपर हैं इसलिए जरूरत पड़ने पर हम इसे बढ़ा सकते हैं। Github मार्कडाउन का समर्थन करता है, VSO अब हाल ही में कोड दृश्य से मार्कडाउन का समर्थन करता है। क्या हमें वास्तव में बहस की जरूरत है। क्षमा करें यदि मैं बहुत प्रत्यक्ष हूं।

मार्कडाउन +1

@ctsni मैं मानता हूं, मार्कडाउन _felt_ पहली नज़र/विचार पर सबसे अच्छी पसंद की तरह। लेकिन जितना अधिक मैं इसके बारे में सोचता हूं, उतना ही यह महसूस होता है कि हम एक चौकोर खूंटी में एक गोल छेद बनाने की कोशिश कर रहे हैं।

मेरे पास स्वीकार्य रूप से एक अच्छा विकल्प नहीं है, इसलिए मैं वास्तव में ज्यादा योगदान नहीं देने के लिए क्षमा चाहता हूं, लेकिन मार्कडाउन का विस्तार करते समय भी मुझे नहीं लगता कि हम कुछ उसी सुंदर, स्वच्छ और साफ मार्कडाउन के साथ समाप्त करेंगे जैसा कि हमने अभी दिया है आवश्यकताएं_।

ऐसा लगता है कि आप मौजूदा एमएसडीएन दस्तावेज को ओपन सोर्स प्रारूप में दोहराना चाहते हैं? क्या वह उचित है? अवलोकन विवरण, ट्यूटोरियल, कोड नमूने और एपीआई दस्तावेज़ीकरण को संभालने के लिए आपको एक समाधान की आवश्यकता है? या यह उसी का एक उपसमूह है?

मुझे विश्वास नहीं है कि एक समाधान है, उपकरणों का एक और संग्रह जिसका आउटपुट जोड़ा जा सकता है। मैं देख सकता हूं कि ReadTheDocs क्या कर रहा है - एकाधिक स्रोतों को दस्तावेज़ीकरण के एक सुसंगत सेट में खींच रहा है। तो मार्कडाउन समाधान के हिस्से के लिए एक वैध उत्तर है (यानी विवरण और ट्यूटोरियल), लेकिन पूरी तस्वीर नहीं है?

खुला प्रश्न: क्या मार्कडाउन से सीधे परिशिष्ट और टीओसी निकालना संभव है? क्या मुझे बहुत मुश्किल नहीं लग रहा है? मैं पक्षपाती हूं। मैंने हजारों पृष्ठों वाले सिस्टम पर काम नहीं किया है... क्षमा करें @shanselman , मैं वास्तव में जो कुछ भी जानता हूं उससे अधिक ज्ञान का योगदान नहीं कर सकता।

@craignicol वर्तमान एमएसडीएन दस्तावेज से कम कुछ भी, मेरे लिए, एक बड़ी गिरावट होगी। मैं हमेशा सबको बताता हूं कि एमएसडीएन पर कुछ बेहतरीन दस्तावेज (संरचना, शब्दों और इसके बारे में सब कुछ) मिलते हैं। मैंने बहुत सारे दस्तावेज देखे हैं लेकिन अधिकांश, यदि सभी नहीं, तो "एमएसडीएन गुणवत्ता" (आईएमएचओ ऑफकोर्स) के करीब भी नहीं आते हैं। यह कहने के बाद: एक बड़ा कारक, निश्चित रूप से, MSDN दस्तावेज़ों के पीछे के लोग MSDN के वास्तविक _content_ की इतनी अच्छी देखभाल कर रहे हैं; संरचना, लेआउट, डिज़ाइन और क्या-क्या-आप दूसरे स्थान पर आते हैं।

शायद स्पर्शरेखा, लेकिन डैश जैसा कुछ होना बहुत अच्छा होगा। वेब विकास इतनी तेजी से विकसित होता है और नई प्रौद्योगिकियां एक दूसरे को प्रभावित करती हैं कि मैं यहां और वहां की जानकारी के लिए खुद को गुगल पाता हूं। एक ही निहित स्थान पर सब कुछ एक्सेस करने में सक्षम होने के कारण जिसे कुछ कीस्ट्रोक्स के माध्यम से लागू किया जा सकता है, अविश्वसनीय रूप से सहायक है। इसी तरह का प्रयास है http://zealdocs.org/ Linux और Windows के लिए।

@craignicol सहमत है, लक्ष्य एमएसडीएन गुणवत्ता वाले दस्तावेज़ हैं जो खुले स्रोत हैं और बनाए रखने और अद्यतित रखने में आसान हैं।

@ciriarte स्फिंक्स डॉक्स को डैश में अनुवाद करने के लिए समर्थन है: https://pypi.python.org/pypi/doc2dash - हमने RTD.org पर स्वचालित डैश सेट निर्माण को देखा है, लेकिन वर्तमान में इसे तैनात नहीं किया है।

मुझे लगता है कि @shanselman ने इसे सबसे ऊपर रखा है - मार्कडाउन एचटीएमएल, वर्ड से ज्यादा जवाब नहीं है, या .txt जवाब होगा। मार्कडाउन मुख्य रूप से एक प्रस्तुति विवरण है - मार्कडाउन (या एचटीएमएल, वर्ड दस्तावेज़, .txt फ़ाइल, आदि) को उत्पन्न करने के लिए कुछ की आवश्यकता होती है।

मुझे लगता है कि मेरा सवाल यह होगा कि आप उस सामग्री को कहां से देखते हैं? क्या यह हाथ से लिखा जाएगा? कोड से स्वतः उत्पन्न? टिप्पणियों में एम्बेड किया गया?

मैं @craignicol से सहमत हूं कि मानव निर्मित नमूने और संपादकीय सामग्री असेंबली एक्सएमएल में उपलब्ध नहीं होने के लिए "स्थैतिक" जीएच मार्कडाउन पृष्ठों के साथ ऑटो जेनरेट की गई सामग्री को मर्ज करने के लिए टूल्स का संग्रह है। आउट परिणाम तब GHPages, PDF या जो कुछ भी स्थिर html हो सकता है।
प्रीप्रोसेसर किसी भी अनाथ स्थिर सामग्री का पता लगा सकता है यदि कोड का नाम बदला/पुनर्निर्मित किया गया है Ie
भाषा समर्थन मूल रूप से तटस्थ के समान संरचना वाले वैकल्पिक फ़ोल्डर हो सकते हैं। गैर-अनुवादित दस्तावेज़ तब तटस्थ पर वापस आ सकते हैं या बिंग अनुवाद के माध्यम से जा सकते हैं।

मूल सुझाव पर पीछे मुड़कर देखें तो प्रारूप के लिए मार्कडाउन पर @ danroth27 और बिल्ड के लिए रीडथेडॉक्स से सहमत होंगे। धन्यवाद।

readthedocs.org + Sphinx का लचीलापन एमएसडीएन के साथ तुल्यता की अनुमति दे सकता है, यदि इसके लिए पहुंच योग्य नहीं है।

@ciriarte शायद एमएसडीएन रीडर के लिए निर्यात योग्य अभिलेखागार के साथ भी समर्थित किया जा सकता है।

@jalcine @erichholscher शानदार लगता है।

@RobThree मुझे आशा है कि वर्तमान में दस्तावेज़ों को बनाए रखने वाली टीम को नए प्रारूप में जाने के लिए राजी किया जा सकता है, अन्यथा यह अभ्यास करने योग्य नहीं है।

@ctsni यह संभव है - मैंने अजगर में एक मार्कडाउन टीओसी पार्सर लिखा है, जो फाइलों की एक सूची लेता है और एक टीओसी उत्पन्न करता है। मुश्किल हिस्सा स्रोत फ़ाइलों की व्याख्या कर रहा है ताकि पार्सर जानता है कि टीओसी और परिशिष्टों को उत्पन्न करने के लिए क्या निकालना है। इंटरमीडिएट प्रारूप, चाहे मार्कडाउन या आरएसटी, अप्रासंगिक है, यह मेटाडेटा प्राप्त कर रहा है जो कि कुंजी है।

एमएसडीएन दस्तावेज़ों को देखते हुए, हाइपरलिंकिंग के लिए मेटाडेटा के दो प्रमुख टुकड़े हैं जो कोड के ट्रैवर्सल की अनुमति देने के लिए एपीआई हुक हैं, और वैचारिक हुक (जैसे सुरक्षा) जो एपीआई को शामिल करने के लिए एक विषय बनाते हैं, ट्यूटोरियल, और वास्तु की जानकारी। यदि एपीआई भाग सही ढंग से किया जाता है, तो मुझे यकीन है कि बाकी सामग्री को सूट के लिए अनुकूलित किया जा सकता है। मुझे डैश का विचार पसंद है, लेकिन मुझे लगता है कि ReadTheDocs और Sphinx MSDN के बारे में मुझे जो पसंद है, उसके सबसे करीब हैं, लेकिन मुझे लगता है कि उन्हें MSDN के समृद्ध विषय और ट्यूटोरियल संरचना को संभालने के लिए अनुकूलित करने की आवश्यकता होगी।

मुझे इस पूरी अवधारणा के बारे में आश्चर्य है। मेरा मतलब है, मुझे दस्तावेज़ श्रृंखला को खोलने और समुदाय को शामिल करने का विचार पसंद है लेकिन एमएसडीएन के बाहर इसे करने से मुझे इच्छा होती है। जो दिखता है (और हो सकता है) .NET की शुरुआत से हम किसी भी माइक्रोसॉफ्ट एपीआई पर कैननिकल संदर्भ के लिए एमएसडीएन गए हैं। WinForms से WebForms तक यह सब एक ही स्थान पर है, अच्छी तरह से क्रॉस-रेफ़रेंस किया गया है और लगातार स्वरूपित किया गया है। मैं मदद नहीं कर सकता, लेकिन आश्चर्य है कि क्या इस प्रयास से प्राप्त होने वाले विखंडन और स्थिरता के नुकसान को पछाड़ने के लिए पर्याप्त लाभ प्रदान करेगा। यह नहीं कहना कि यह पूरी तरह से इसके लायक नहीं होगा, और संभवत: ये चर्चाएं पहले ही हो चुकी हैं, लेकिन विचार के लिए भोजन।

स्फिंक्स के लिए +1

मैं वास्तव में रीडथेडॉक्स प्रारूप और उपकरण खोदता हूं और वे कई परियोजनाओं के लिए बहुत अच्छा काम करते हैं। पहिया का पुन: आविष्कार न करें। मार्कडाउन ठीक है। मुझे लगता है कि यदि आप इसे मार्कडाउन के साथ वर्णित नहीं कर सकते हैं तो आप कुछ जटिल करने की कोशिश कर रहे हैं। अगर प्रारूप और घर्षण का स्तर कम है तो मुझे योगदान करने में खुशी होगी। एमएसडीएन विकी वहां पहुंचने की तरह था, लेकिन इसका अधिकांश हिस्सा बंद हो गया था और यह पुरानी सामग्री की बंजर भूमि बन गई थी। ऐसा लगता है कि PHP समुदाय अपने डॉक्टर सिस्टम के साथ इसे काफी अच्छी तरह से कर रहा है (हालांकि उनकी टिप्पणी कभी-कभी खरगोश के छेद से नीचे जाती है)। मुझे लगता है कि मार्कडाउन के साथ इसे सरल रखना काम करेगा, लेकिन "मास्टर दस्तावेज़" या इसे एक साथ खींचने और इसे सिंक में रखने के लिए शायद किसी प्रकार का अनुक्रमण/पीढ़ी उपकरण होना चाहिए। लगभग हजारों मार्कडाउन स्निपेट/दस्तावेजों के लिए एक निर्भरता निर्माण प्रणाली की तरह।

मुझे लगता है कि टेक्स्ट अंशों के लिए मार्कडाउन। मेटा-डेटा के लिए Yaml फ्रंट-मैटर या json फ़ाइलें। कस्टम .NET आधारित प्रोसेसर एक्स्टेंसिबल प्लगइन मॉडल के साथ आसानी से TOC और टेबल आदि जैसे फैंसी सामान के लिए सिंटैक्स जोड़ने के लिए या मार्कडाउन के समान ही rst का उपयोग करें।

बस एमएसडीएन ओपन सोर्स बनाएं। जब तक यह गड़बड़ न हो :)

@somedave आपके बारे में नहीं जानता, लेकिन मुझे एमएसडीएन पर सामग्री ढूंढना कठिन और कठिन लग रहा है, विशेष रूप से गैर-वर्तमान ढांचे पर उच्च स्तरीय वास्तुशिल्प दस्तावेज। कोड से जुड़े दस्तावेज़ीकरण, और सभी उपलब्ध ओपन सोर्स और संस्करण नियंत्रण के तहत एक बड़ा सुधार है।

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

@ danroth27 , क्या आप पूरी तरह से जावाडोक/xmldoc दस्तावेज़ीकरण, या सामान्य रूप से दस्तावेज़ीकरण के बारे में बात कर रहे हैं? यानी यह http://www.asp.net/aspnet/overview/authentication-and-identity बनाम https://msdn.microsoft.com/en-us/library/system.web.mvc.ivalueprovider (v=vs. 118).एएसपीएक्स?

डगेनी https://github.com/angular/dgeni

निश्चित रूप से HTML लेकिन स्थानीय रूप से इसका उपयोग करने की क्षमता के साथ - आइए इसे स्थानीय IIS (या केवल स्थानीय रूप से) पर स्थापित करने के लिए कहें।

कृपया Sandcastle और SHFB पाइपलाइन पर निर्माण करें और इसे बेहतर (सरल और 'ओपन सोर्स फ्रेंडली') बनाने में मदद करें। मार्कडाउन ऑथरिंग (अवधारणात्मक सामग्री के लिए) और प्रतिपादन के लिए समर्थन जोड़ा जा सकता है (इस दिशा में कुछ शुरुआत पहले ही की जा चुकी है)।
लोकप्रिय (SHFB के लिए आधा मिलियन डाउनलोड) .NET-आधारित टूल का समर्थन करने में बहुत सारे डॉगफ़ूड-मूल्य हैं। मुहावरे उपकरण से प्रोजेक्ट में ही लीक हो जाते हैं। उदाहरण के लिए, .NET के साथ बहु-भाषा कोड स्निपेट का समर्थन करना वास्तव में मूल्यवान है, ताकि VB.NET और F# को प्लेटफॉर्म पर व्यवहार्य भाषाओं के रूप में बनाए रखा जा सके। सैंडकैसल और एमएसडीएन-स्टाइल आउटपुट यह बहुत अच्छा करता है।

समस्या यह है कि रीस्ट्रक्चर्ड टेक्स्ट यह है कि यह मार्कडाउन की तरह है, लेकिन पूरी तरह से नहीं। इस प्रकार यह सीखने का एक और प्रारूप बन जाता है। SHFB वर्तमान में काम पूरा कर लेता है, लेकिन यह सुखद अनुभव नहीं है। कुछ न कुछ से बेहतर है और इसे इतने लंबे समय तक जीवित और अद्यतन रखने के लिए ईवुड्रूफ़ का मेरा अमिट धन्यवाद है।

.NET डेवलपर के दृष्टिकोण से, .NET के लिए वास्तव में एक अच्छा ओपनसोर्स डॉक जनरेशन टूल अभी भी आवश्यक/वांछित है। मेरी राय में यह अधिमानतः एक उपकरण है जो लंबे फॉर्म टेक्स्ट को मार्कडाउन के साथ लिखने की अनुमति देता है क्योंकि यह कुछ ऐसा है जो ज्ञात और उपयोग करने में सुखद है।

मुझे पता है कि एमएस टीम शायद दरवाजे से बाहर एएसपीनेट 5 शिप करने के लिए कुछ उठना और दौड़ना चाहती है, लेकिन यह डेवलपर्स को महसूस होने वाले लंबे समय तक दर्द को छूती है।

मेरा एक सुझाव कॉमनमार्क मॉड्यूल विकसित करने के लिए http://commonmark.org/ के साथ काम करना है और https://github.com/Knagis/CommonMark.NET जैसे कुछ को बढ़ाने पर विचार करना है।

अन्यथा, कम से कम पहली रिलीज़ के बाद दस्तावेज़ सिस्टम को बदलने के लिए तैयार रहें ताकि समुदाय किसी ऐसी चीज़ से न चिपके, जिसका उपयोग करने के लिए बहुत अधिक घर्षण हो.. फिर से।

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

@ryanbnl हम एपीआई संदर्भ प्रलेखन और वैचारिक सामग्री दोनों के लिए एक समाधान की तलाश में हैं।

@michaelherndon मैं पूरी तरह से सहमत हूं कि .NET के लिए एक अच्छे ओपन सोर्स डॉक जनरेशन टूल की आवश्यकता है! आप यह भी सही कह रहे हैं कि हमें ASP.NET के लिए कुछ जल्दी से शुरू करने और चलाने की आवश्यकता है। यदि कोई समुदाय समर्थित .NET आधारित दस्तावेज सामने आता है तो हम निश्चित रूप से इसे अपनाने के लिए तैयार होंगे। हम यह भी मानते हैं कि दस्तावेज़ों को ऑफ़लाइन एक्सेस करने का एक तरीका होना एक आवश्यकता है।

ठीक है, यह स्पष्ट है :) एपीआई दस्तावेज़ों के लिए यह डॉक्सिजन को देखने लायक है। यह वास्तव में शक्तिशाली है, और वर्ग आरेख उत्पन्न कर सकता है (जो कुछ स्थितियों में अमूल्य हो सकता है)। मैंने पिछले साल डॉक्सिजन/सैंडकैसल की विस्तृत तुलना की थी, अगर इससे मदद मिलेगी तो मैं आपको एक प्रति भेज सकता हूं? इसमें बहुत सारे उदाहरण हैं + एक चरण-दर-चरण इंस्टॉल गाइड (डॉक्सिजन स्थापित करना मुश्किल है);)

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

@farrukhsubhani उपकरण शायद वीएस पर निर्भर नहीं होना चाहिए: यदि हम चाहते हैं कि मैक और लिनक्स उपयोगकर्ता एएसपी.

मैं देख रहा हूँ कि अब स्रोतों में बहुत कम दस्तावेज़ीकरण टिप्पणियाँ हैं। हालांकि यह फ़ाइल से फ़ाइल में भिन्न होता है। क्या संदर्भ दस्तावेज़ों के लिए इनपुट के रूप में इसका उपयोग करने के बारे में कोई निर्णय लिया गया है, या यह व्यक्तिगत डेवलपर्स पर निर्भर है?

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

हो सकता है कि अन्य लोग हिंसक रूप से असहमत हों, लेकिन मैं विशेष रूप से उसके लिए संपादन /* */ शैली टिप्पणियों और संरेखित * की श्रृंखला को नापसंद करता हूं। कृपया मुझे बताएं कि मुझे चिंता करने की ज़रूरत नहीं है;)

@ डैनरोथ27

इसके बारे में कम से कम पढ़ने और सोचने के लिए बस कुछ विचार और अग्रिम धन्यवाद।

एक लिंक या शीर्षक जैसी साधारण चीजों को इंजेक्ट करने के लिए पुनर्रचित पाठ PITA की तरह लगता है। मैं सप्ताह के किसी भी दिन जावाडोक कोड टिप्पणियां या सिर्फ वेनिला एचटीएमएल लेता हूं।

============
h1
============

***************
h2
***************

h3
------------------

check out the _aspnet homepage.

.. _aspet: http://www.aspnet.com/

मैं अनुरोध करना चाहता हूं कि aspnet आंतरिक रूप से एक .net दस्तावेज़ीकरण उपकरण पर कुछ लक्ष्य/स्पेश निर्धारित करने पर समुदाय के साथ काम करने पर चर्चा करे और शायद कुछ रचनात्मक प्रोत्साहन जैसे मान्यता या उन पंक्तियों के साथ कुछ प्रदान करे। मैं आप सभी से .NET फाउंडेशन के माध्यम से परियोजना की स्थापना पर चर्चा करने के लिए भी कहता हूं। यह सीएस छात्रों के काम करने के लिए प्रोजेक्ट जैसे कोड की एक सभ्य इंटर्न/गर्मी के रूप में भी काम कर सकता है क्योंकि इसमें एक पार्सर बनाने की संभावना अधिक होगी।

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

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

कहा जा रहा है, अगर इसे अभी शुरू किया गया था, तो यह .NET कोर 5 का उपयोग करने के लिए तैयार हो सकता है।

@ericwj सभी सार्वजनिक एपीआई को उन पर एक्सएमएल दस्तावेज़ टिप्पणियां रखने के लिए ¹ की आवश्यकता होती है। हालांकि, परियोजना की शुरुआत में हमने उस आवश्यकता को कम कर दिया क्योंकि एपीआई पर बहुत सारे दस्तावेज़ लिखना जो हमें पता था कि महत्वपूर्ण रूप से बदल जाएगा, काफी हद तक व्यर्थ प्रयास माना जाता था। हालांकि, पिछले कुछ महीनों से सभी प्रतिबद्धताओं में महत्वपूर्ण मात्रा में दस्तावेज मौजूद होने चाहिए। वास्तव में अभी भी कई छेद हैं, लेकिन यह दस्तावेज़ीकरण प्रदान करना टीम का दायित्व है। दस्तावेज़ों को पैच अप करते समय, हम अधिक महत्वपूर्ण एपीआई पर ध्यान केंद्रित करते हैं जो हमें लगता है कि डेवलपर्स तक पहुंच प्राप्त करेंगे, और कम-दस्तावेज स्थिति में अधिक गूढ़ एपीआई को फिर से लागू करेंगे (जिसे हम अभी भी एक दिन भरने की उम्मीद करते हैं)।

¹ आवश्यक _विशेषण_

कुछ ऐसा जो वैकल्पिक नहीं है।
इसका मतलब यह भी हो सकता है कि XML दस्तावेज़ टिप्पणियों के संदर्भ में _is_ वैकल्पिक हो।

@michaelherndon BTW यह प्रोजेक्ट पहले से ही .NET Foundation का हिस्सा है ।

@Eilon संदर्भ एक .net दस्तावेज़ीकरण उपकरण जोड़ने के बारे में बात कर रहा था, न कि एस्पनेट 5।

@michaelherndon आह मिल गया, धन्यवाद!

@shanselman @ danroth27 , मैंने पिछले शुक्रवार को अपने प्रबंधक को सूचित किया है और इसने उस थ्रेड के बारे में MSDN के प्रधान समूह प्रधान मंत्री से संपर्क किया है। उन्हें आपके दस्तावेज़ीकरण मामले के बारे में आपसे संपर्क करना चाहिए। आपका दिन शुभ हो।

@michaelherndon मैं मानता हूं कि हेडर सिंटैक्स थोड़ा और वर्बोज़ है। एक अन्य सामान्य मामला दस्तावेज़ीकरण में किसी फ़ंक्शन, या पृष्ठ से लिंक करना है, जहां आरएसटी चमकता है:

More Info
=========

This function wraps :func:`bar`, 
more info in :doc:`bar-like-functions` or on our `website <http://www.aspnet.com>`_.

मार्कडाउन में कुछ ऐसा ही करना:

### More Info

This function wraps [bar](func:bar), 
more info in [Bar Like Functions](bar-like-functions.md) or on our [website](http://www.aspnet.com).

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

इन पंक्तियों के साथ एक और दिलचस्प बात यह है कि आरएसटी और एमडी को एक संगत तरीके से कैसे लिखा जाए: https://gist.github.com/dupuy/1855764। मार्कडाउन आम तौर पर आरएसटी-स्टाइल हेडर का समर्थन करता है, ताकि हेडर स्टाइल दोनों में काम करे।

यदि यह शो-स्टॉपर है तो आप एक्सटेंशन के साथ मूल मार्कडाउन सिंटैक्स को समझने के लिए स्फिंक्स या अन्य टूलिंग को भी कॉन्फ़िगर कर सकते हैं।

मुझे याद है कि 18 महीने पहले एमवीपी में ओएसएस पैनल में कहा गया था कि .NET में दस्तावेज़ीकरण के लिए कोई अच्छा विकल्प नहीं था :stuck_out_tongue_closed_eyes:

जो मैं वास्तव में देखना चाहता हूं वह मार्कडाउन या आरएसटी प्लस .NET एक्सएमएल दस्तावेज से सामग्री की एक तालिका उत्पन्न करने का एक तरीका है। इसके बाद इसे readthedocs या github wiki जैसी किसी चीज़ में लोड किया जा सकता है।

Sandcastle में .NET XML दस्तावेज़ पढ़ने के लिए पहले से ही बहुत सारे कोड हैं और यह नई शैलियों और आउटपुट प्रकारों के साथ एक्स्टेंसिबल है। आप उस पर निर्माण कर सकते हैं।

मैं इस सूत्र को कैसे देखूं और यह पता लगाऊं कि निष्कर्ष क्या था, क्या कोई निर्णय लिया गया था, और यदि हां, तो वह क्या था?

https://github.com/aspnet/Docs

आप लोग DocFX का उपयोग क्यों नहीं कर रहे हैं?

जब हमने ASP.NET 5 के लिए प्रलेखन लिखना शुरू किया तो docfx परियोजना अभी भी विकास के प्रारंभिक चरण में थी। स्फिंक्स अभी भी अधिक परिपक्व है और इसमें समृद्ध दस्तावेज़ीकरण ढांचा है। उसके ऊपर रीड द डॉक्स वास्तव में एक अच्छा प्रलेखन होस्टिंग समाधान प्रदान करता है।

उस ने कहा, हम .NET के लिए दस्तावेज़ीकरण समाधान के रूप में docfx प्रयास का समर्थन करते हैं और यह देखना रोमांचक है कि docfx अब खुला स्रोत है! हम पहले से ही एपीआई संदर्भ दस्तावेज़ीकरण के लिए docfx का उपयोग करने की योजना बना रहे हैं और हम docfx के परिपक्व होने पर आगे बढ़ने की उम्मीद करते हैं।

गेट से बाहर दो अलग-अलग दिशाओं में जाने में शर्म आती है जब docfx ऐसा प्रतीत होता है जो MSDN उपयोग कर रहा है, कम से कम अंतर्निहित विषयों के अनुसार।

@simonmurdock docfx (अभी तक) ऑफ़लाइन दस्तावेज़ों के निर्माण का समर्थन नहीं करता है, जैसे PDF

हाँ @cocowalla मैं दस्तावेज़ीकरण के साथ संघ की स्थिति के बारे में शाश्वत प्रवाह में हूँ। अब मैं अपने लेख स्फिंक्स में लिख रहा हूं, लेकिन स्फिंक्स-एकीकृत एपीआई दस्तावेज़ उत्पन्न करने का कोई वास्तविक अच्छा तरीका नहीं है।

वर्तमान योजना सभी लेखों के लिए Sphinx है और DocFX के आउटपुट के लिए एक अलग साइट है, जब तक कि Sphinx ApiDocs थोड़ा अच्छा न दिखे।

@simonmurdock यहां हम वर्तमान में docfx और Sphinx autoapi एक्सटेंशन के संयोजन का उपयोग करके ASP.NET के लिए API रेफ डॉक्स जेनरेट करने के लिए क्या करते हैं: https://github.com/aspnet/apidocs। यह अभी भी थोड़ा कठिन है, लेकिन हम डॉक्स पढ़ें लोगों के साथ सुधार के एक समूह पर काम कर रहे हैं।

@ danroth27 इतने वोट रुपये के लिए थे, हालाँकि, आखिरकार आपने एमडी को चुना? जब मैं https://docs.microsoft.com/en-us/aspnet/core/ में किसी भी पृष्ठ पर संपादित करें पर क्लिक करता हूं, तो मुझे गिटहब पर एमडी स्रोत फ़ाइल दिखाई देती है।
तो एमडी क्यों?

हम ASP.NET Core और EF Core डॉक्स के लिए कुछ समय के लिए RST और http://readthedocs.com का उपयोग कर रहे थे, लेकिन हाल ही में Microsoft ने http://docs.microsoft.com पर अपना स्वयं का डॉक्स इंफ्रास्ट्रक्चर बनाया, इसलिए हम यहां चले गए उसके साथ संरेखित करें। जबकि मार्कडाउन एक दस्तावेज़ीकरण भाषा के रूप में परिपक्व नहीं है, जो कि पुनर्रचित पाठ के रूप में है, यह व्यापक दर्शकों के लिए अधिक परिचित है। यहां तक ​​कि रीड द डॉक्स भी इस कारण से दोनों प्रारूपों का समर्थन करता है।

@ danroth27 क्या इसका मतलब यह है कि Microsoft ने अपना स्वयं का गैर-खुला स्रोत प्रलेखन जनरेटर/इंजन बनाया है जो मार्कडाउन का उपयोग करता है? https://docs.microsoft.com के पीछे क्या रहता है?

क्या इसका मतलब यह है कि माइक्रोसॉफ्ट ने अपना स्वयं का गैर-खुला स्रोत प्रलेखन जनरेटर/इंजन बनाया है जो मार्कडाउन का उपयोग करता है?

नहीं। https://docs.microsoft.com के पीछे का डॉक इंजन DocFX है और यह .NET पर बनाया गया है और पूरी तरह से खुला स्रोत है। यह अपने प्रारूप के लिए मार्कडाउन का उपयोग करता है।

नमस्ते

मुझे इसे पोस्ट करने में थोड़ी देर हो सकती है।

मैं बस सोच रहा हूं कि क्या कोई एपीआई या ढांचा या टूलिंग है जो हमें https://docs.microsoft.com के लिए एक जैसी दस्तावेज़ीकरण साइट बनाने देती है? मुझे व्यक्तिगत रूप से पसंद है कि Microsoft दस्तावेज़ कैसे प्रस्तुत किया जाता है, @ danroth27 ने DocFX का उल्लेख किया है जो कि इंजन का उपयोग किया गया था, मैं सिर्फ यह जानना चाहता हूं कि क्या साइट ही कुछ ऐसा है जो जमीन से ऊपर किया गया है या क्या कोई टेम्पलेट या पैकेज है जिसे हम कर सकते हैं उसी रूप और अनुभव को उत्पन्न करने के लिए उपयोग करें? बिल्कुल वही नहीं लेकिन कुछ ऐसा जिसे हम संशोधित कर सकते हैं :)

धन्यवाद!
जूड अलक्विजा।

जितना अधिक मैंने DocFx के बारे में पढ़ा, उतना ही मैं इसे पसंद कर रहा हूँ - इसे जल्द ही आज़माऊँगा।

हम पहिया का पुन: आविष्कार किए बिना आंतरिक रूप से https://docs.microsoft.com/ जैसी अपनी स्वयं की दस्तावेज़ीकरण वेबसाइट कैसे बना सकते हैं? हम अजगर दस्तावेज़ों के लिए एक होस्टेड रीडथेडॉक्स और सी/सी ++ दस्तावेज़ों के लिए एक होस्टेड डॉक्सिजन का उपयोग करते हैं।

सभी एपीआई डॉक्स एक ही छत के नीचे प्राप्त करने का सबसे अच्छा तरीका क्या है? इस धागे को पढ़ने से, ऐसा लगता है कि बहुत से लोग स्फिंक्स/रीडथेडॉक्स का उपयोग करते हैं लेकिन आप अपने .XML दस्तावेज़ों को इन उपकरणों के लिए सही प्रारूप में कैसे परिवर्तित कर रहे हैं?