Aspnetcore: ما هو التنسيق الذي يجب أن نستخدمه لوثائق ASP.NET 5؟

http://shfb.codeplex.com

أو اصنع شيئًا جديدًا تمامًا.

سيكون إنشاء GH Markdown جيدًا قبل المعالج أمرًا ممتازًا.

+1 لـ Markdown (أو Markdown بنكهة GitHub). قد تفتقر إلى بعض الميزات ولكنها معروفة جيدًا وسهلة التعلم والاستخدام. أعتقد أنه قد يعتمد على القرار النهائي بشأن مكان استضافته ، كما ذكرت بعض الخيارات.

مرحبا دانييل،
شكرا لمساهمتك.
بصفتي مطورًا مبتدئًا ، أجد أنه من السهل تنظيم المستند كعناوين في الشريط الجانبي ، على غرار http://rustbyexample.com/
(IMHO)

-1 على صنع شيء جديد.
+1 للعمل على شيء موجود وتحسينه إن أمكن.

@ danroth27 هل يمكنك مشاركة المزيد من التفاصيل حول احتياجات التوثيق الخاصة بك وما هي ميزات نظام التوثيق الناضج الذي تحتاجه؟

أعتقد أن قول "استخدام Markdown" مفرط في التبسيط.

Markdown هو DSL لـ HTML. هذا كل شئ. هل ستقول حقًا "تم حل محرّر المستندات ، فلنستخدم HTML!"

نحتاج إلى نظام توثيق فعلي مثل Sphinx.

• Markdown لا يمكنه إنشاء ToC.
• Markdown لا يمكنه الربط بين الموضوعات (عليك القيام بالروابط يدويًا)
• Markdown لا يمكنه القيام بأشياء مثل دعم متعدد اللغات أو دعم متعدد الإصدارات.

أنا أؤيد ericholscher 's Read The Docs ، ولكن بشكل أكثر تحديدًا Sphinx و reStructuredText.

أو لن يتم إطلاق استخدام DOxygen و vNext ؛)

ماذا عن شيء مشابه لـ Roslyn أو AngularJS؟ http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown يعمل بشكل جيد للغاية مع معظم المشاريع الأخرى على GitHub. +1 لعملية Markdown.

shanselman ، روابط نسبية؟

أعتقد أن استخدام Sphinx سينجح.
أمثلة على issafram هنا:
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

akoeplinger نود شيئًا يمكننا بسهولة إنشاء جدول محتويات منه وربطه بسهولة عبر الصفحات. نود أيضًا شيئًا يمكنه إنشاء مجموعة متنوعة من تنسيقات المستندات بما في ذلك HTML و PDF و ePub. يجب أن تكون المستندات قابلة للقراءة أيضًا على الأجهزة المحمولة.

يعدissafram Markdown رائعًا عندما تكون مستنداتك مائة صفحة ، وعلى الأرجح أقل. لكن آلاف الصفحات وجداول المحتويات المتشابكة؟ الحفاظ على الملاحق محدثة؟ ربط مستندات ASP.NET و .NET؟ ستكون فوضى.

ضع في اعتبارك ، إذا كنت تريد أن يكون هذا مفتوح المصدر حقًا ، وبالتالي شيئًا يشجع المساهمة ، يجب أن يكون النظام بسيطًا قدر الإمكان ، بدون منحنى تعليمي. لا يمكن لـ Markdown إنشاء ToC بمفرده ، ولكن يمكن أن تنشئ التعليمات البرمجية البسيطة نسبيًا ToC من Markdown.
نحن في Orchard سعداء جدًا بنظامنا ، وهو Markdown على Github بالإضافة إلى موقع Azure مع القليل جدًا من التعليمات البرمجية (لفهرسة Lucene والبحث ، بالإضافة إلى إنشاء ToC) التي يتم تحديثها تلقائيًا في كل مرة يتم فيها دفع الريبو. أدوات مألوفة وبسيطة للغاية.
الشيء الوحيد الذي لا يعجبني في ذلك هو نقص البيانات الوصفية (نستخرج العناوين من أسماء الملفات) ، ولكن هناك حلول لذلك أيضًا ، مثل رؤوس Jeckyll's YAML (بدعم من Github) أو تنسيق Snippable الخاص بي.

issafram هذا لا يعمل بشكل جيد في قواعد البيانات الضخمة التي تحتوي على الكثير من المستندات وإعادة البناء على سبيل المثال. إعادة تسمية فئة وداعا وداعا الروابط ذات الصلة.

_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

بالتأكيد ، هذا رائع. مجرد إعطاء تجربتنا. أنا أفهم أنك في نطاق مختلف.

rST هو الخيار الأفضل هنا ، عملي. كونه ASP.NET ، فإن امتلاك شيء ذكي بما يكفي لتحديث فهارسه (من ToC أو حتى من وجهة نظر قائمة الفصل) ربما يكون أولوية قصوى.

من الناحية المثالية ، أود تشغيل شيء ما في Build Workflow للاستيلاء على جميع ملفات .XML التي تم إنشاؤها من الثنائيات ثم وضعها في معالج لإنشاء الملفات التي يتم نشرها بعد ذلك على الخادم. الأدوات الدقيقة .... ليس لدي أدنى فكرة. لقد تم ذكر الكثير. أود أن أوصي ببناء المصدر الخاص بك ومفتوح المصدر. نعم نعم ... بناء مقابل شراء النقاش ولكني أكره استخدام الأدوات التي لديها موارد غير مُدارة مثل بعض ما سبق. على أي حال ، هذا يبدو مثاليًا ... ربما لديك قيود الميزانية والوقت وما لا.

issafram إذا انتهى بك الأمر جميعًا باستخدام Sphinx / RTD ، فقد يكون شيء ما على غرار Breathe نهجًا عمليًا: http://breathe.readthedocs.org/en/latest/ - التكامل مع Sphinx & Doxygen هو الذي يستخدم ملفات Doxygen XML.

issafram يبدو لي أنك تصف SHFB ... (في الواقع Sandcastle ، SHFB يجعلها أكثر متعة في الاستخدام: P)

نعم ، أنت بحاجة إلى معالج أولي / معالج لاحق ، يمكنك ربط النسبية داخل المستند باستخدام GHMD لـ TOC. بالنسبة لمشاريعنا ، قمنا بتدوير منطقتنا الخاصة بشكل أساسي بأخذ .Net doc XML والمبنية على الاتفاقية مدمجة مع رمز عينة ومحتوى ثابت آخر مكتوب في MD. النتيجة النهائية هي HTML.

إن وجود محتوى تحريري ورمز ثابت في MD سيجعل من السهل القيام بالعلاقات العامة. ما أحبه في تخفيض السعر كتنسيق مصدر هو أنه مخصص أنظف من HTML و XML وما إلى ذلك. مما يجعل التدقيق سهلاً ومناسبًا تمامًا للتحكم في المصدر.

نحن بحاجة إلى أداة توثيق قائمة على الاتفاقية نظيفة وبسيطة لـ .Net ، لم أجد واحدة ، إذا كان هناك من ، أود أن يتم إعلامي. وسأكون سعيدًا بالمساهمة في ذلك.

بالنسبة لقابلية الصيانة والربط عبر المشاريع. Intersphinx هو وسيلة قوية للقيام بذلك بطريقة دلالية. يسمح لك بفهرسة جميع المراجع (سواء أكانت رمزًا أم نثرًا) وربطها صراحةً عبر المشاريع.

المستندات هنا: http://sphinx-doc.org/latest/ext/intersphinx.html

هذا هو نوع الوظيفة التي لا يمتلكها شيء مثل Markdown بأي طريقة أعرفها.

متفقًا على أن تخفيض السعر ليس هو الحل الأفضل ، لكننا نحتاج حاليًا إلى حل بسيط. مرحبًا ، نحن مطورون لذا يمكننا تمديد هذا إذا لزم الأمر. يدعم Github تخفيض السعر ، يدعم VSO الآن تخفيض السعر من عرض الكود. هل نحن حقا بحاجة إلى مناقشة. آسف إذا كنت مباشرة جدا.

تخفيض السعر +1

ctsni أعترف ، Markdown _felt_ مثل الخيار الأفضل للوهلة الأولى / الفكر. لكن كلما فكرت في الأمر ، شعرت وكأننا نحاول أن نطرق في ربط مربع في حفرة مستديرة.

ليس لدي بديل جيد باعتراف الجميع ، لذلك أعتذر لعدم المساهمة كثيرًا في الواقع ، ولكن حتى عند تمديد Markdown ، لا أشعر بأننا سننتهي بشيء مماثل لـ Markdown الجميل والنظيف والأنيق كما فعلنا الآن _ بالنظر إلى المتطلبات_.

يبدو أنك تريد نسخ وثائق MSDN الموجودة بتنسيق مفتوح المصدر؟ هذا يشتعل؟ هل تحتاج إلى حل للتعامل مع أوصاف النظرة العامة والبرامج التعليمية وعينات التعليمات البرمجية ووثائق API؟ أم أنها مجموعة فرعية من ذلك؟

لست مقتنعًا بوجود حل واحد ، أكثر من مجموعة من الأدوات التي يمكن دمج مخرجاتها. يمكنني رؤية ما تقوم به ReadTheDocs - سحب مصادر متعددة في مجموعة واحدة متماسكة من الوثائق. إذن Markdown هو إجابة صحيحة لجزء من الحل (أي الأوصاف والبرامج التعليمية) ، لكن ليست الصورة الكاملة؟

سؤال مفتوح: هل من الممكن استخراج الملاحق و TOC مباشرة من التخفيضات الشرائية؟ لا تبدو صعبة للغاية بالنسبة لي؟ أنا منحاز. لم أعمل على نظام يحتوي على آلاف الصفحات ... آسف shanselman ، لا يمكنني حقًا المساهمة بحكمة تتجاوز ما أعرفه.

craignicol أي شيء أقل من وثائق MSDN الحالية سيكون ، بالنسبة لي ، بمثابة خيبة أمل كبيرة. أخبر الجميع دائمًا أن بعضًا من أفضل التوثيق (من حيث الهيكل والصياغة وكل شيء يتعلق به) موجود على MSDN. لقد رأيت الكثير من الوثائق ولكن معظمها ، إن لم يكن كلها ، لا تقترب حتى من "جودة MSDN" (IMHO بالطبع). بعد قولي هذا: هناك عامل كبير ، بالطبع ، هو أن الأشخاص الذين يقفون وراء مستندات MSDN يعتنون جيدًا بالمحتوى الفعلي لـ MSDN ؛ يأتي الهيكل والتخطيط والتصميم وماذا لديك في المرتبة الثانية.

ربما يكون عرضيًا ، لكن سيكون من الجيد جدًا وجود شيء مثل اندفاعة . يتطور تطوير الويب بسرعة كبيرة وتؤثر التقنيات الجديدة على بعضها البعض لدرجة أنني أجد نفسي أبحث في Google عن أجزاء من المعلومات هنا وهناك. أن تكون قادرًا على الوصول إلى كل شيء في مكان واحد محصور يمكن استدعاؤه عن طريق بعض ضغطات المفاتيح ، هو أمر مفيد للغاية. هناك جهد مماثل http://zealdocs.org/ لنظامي Linux و Windows.

craignicol متفق عليه ، الهدف هو الحصول على مستندات MSDN عالية الجودة ومفتوحة المصدر وأسهل في الحفاظ عليها وتحديثها.

ciriarte هناك دعم لترجمة مستندات Sphinx إلى Dash: https://pypi.python.org/pypi/doc2dash - لقد نظرنا في إنشاء مجموعة Dash تلقائيًا على RTD.org ، ولكن لم يتم نشرها حاليًا.

أعتقد أن shanselman وضعها أفضل ما في الأعلى - Markdown ليس هو الحل أكثر من HTML أو Word أو .txt سيكون الحل. Markdown هو في الأساس وصف للعرض التقديمي - ما هو مطلوب هو شيء لإنشاء Markdown (أو HTML ، مستند Word ، ملف .txt ، إلخ.)

أعتقد أن سؤالي سيكون من أين ترى هذا المحتوى يأتي؟ هل ستكون مكتوبة بخط اليد؟ تم إنشاؤه تلقائيًا من الرمز؟ مضمنة في التعليقات؟

أتفق مع craignicol على مجموعة من الأدوات لدمج المحتوى الذي تم إنشاؤه تلقائيًا مع صفحات GH Markdown "الثابتة" لعينات من صنع الإنسان والمحتوى التحريري غير متوفرة في XML التجميع. يمكن أن تكون نتيجة الإخراج ثابتة html في GHPages أو PDF أو أيًا كان.
يمكن للمعالج المسبق اكتشاف أي محتوى ثابت معزول إذا تمت إعادة تسمية / إعادة بناء الكود أي
يمكن أن يكون دعم اللغة في الأساس مجلدات اختيارية بنفس بنية الحيادية. يمكن للمستندات غير المترجمة بعد ذلك الرجوع إلى الوضع المحايد أو الانتقال إلى ترجمة Bing.

إذا نظرنا إلى الوراء في الاقتراح الأصلي ، فسوف نتفق مع @ danroth27 على تخفيض السعر من أجل التنسيق و readthedocs للبناء. شكرا.

يمكن أن تسمح مرونة readthedocs.org + Sphinx بالتكافؤ مع MSDN ، إن لم يكن مناسبًا لها.

ciriarte ربما يمكن دعم ذلك أيضًا مع الأرشيفات القابلة للتصدير لقارئ MSDN.

jalcineericholscher تبدو رائعة.

RobThree ، آمل أن يتم إقناع الفريق الذي يقوم بصيانة المستندات حاليًا بالانتقال إلى التنسيق الجديد ، وإلا فإن هذا التمرين لا يستحق القيام به.

ctsni من الممكن - لقد قمت بكتابة محلل ToC للعلامة التجارية في لغة python ، والذي يأخذ قائمة بالملفات وينشئ ToC. يتمثل الجزء الصعب في وضع تعليقات توضيحية على الملفات المصدر حتى يعرف المحلل اللغوي ما يجب استخراجه لإنشاء ToC والملاحق. التنسيق الوسيط ، سواء كان Markdown أو rST ، غير ذي صلة ، إنه الحصول على البيانات الوصفية بشكل صحيح.

بالنظر إلى مستندات MSDN ، فإن الجزأين الأساسيين من البيانات الوصفية الأكثر أهمية للارتباط التشعبي هما خطاطيف واجهة برمجة التطبيقات ، للسماح باجتياز الكود ، والخطافات المفاهيمية (مثل الأمان) التي تنشئ موضوعًا ليشمل واجهة برمجة التطبيقات ، والبرامج التعليمية ، والمعلومات المعمارية. إذا تم تنفيذ جزء API بشكل صحيح ، فأنا متأكد من أنه يمكن تكييف بقية المحتوى ليناسب. تعجبني فكرة Dash ، لكنني أعتقد أن ReadTheDocs و Sphinx هما أقرب ما رأيته لما أحبه في MSDN ، لكنني أعتقد أنهما سيحتاجان إلى تكييف للتعامل مع الموضوع الغني وبنية البرنامج التعليمي التي تمتلكها MSDN.

أنا أتساءل عن هذا المفهوم برمته. أعني ، أحب فكرة المصدر المفتوح لسلسلة التوثيق وإشراك المجتمع ، لكن القيام بذلك خارج MSDN يمنحني الإرادة. من ما يبدو (وربما كان) بداية .NET ، انتقلنا إلى MSDN كمرجع أساسي في أي Microsoft API. من WinForms إلى WebForms ، كل ذلك في مكان واحد ، ومراجع بشكل جيد ومنسق بشكل متسق. لا يسعني إلا أن أتساءل عما إذا كان المكتسب من هذا المسعى سيوفر فائدة كافية تفوق التجزئة وفقدان الاتساق. عدم القول إن الأمر لن يستحق ذلك تمامًا ، ومن المفترض أن هذه المناقشات قد تمت بالفعل ، ولكنها غذاء للتفكير.

+1 لأبو الهول

إنني حقًا أحفر تنسيق readthedocs وأدواتها وهي تعمل جيدًا للعديد من المشاريع. لا تعيد اختراع العجلة. تخفيض السعر جيد. أعتقد أنه إذا كنت لا تستطيع وصف الأمر بخفض السعر ، فأنت تحاول أن تفعل شيئًا معقدًا للغاية. سأكون سعيدًا للمساهمة إذا كان التنسيق ومستوى الاحتكاك منخفضًا. ويكي MSDN كان نوعا ما يصل إلى هناك ، ولكن تم إغلاق معظمه وأصبح أرض قاحلة من المحتوى القديم. يبدو أن مجتمع PHP يقوم بذلك بشكل جيد إلى حد ما مع نظام المستندات الخاص بهم (على الرغم من أن تعليقاتهم تنخفض أحيانًا إلى ثقوب الأرانب). أعتقد أن إبقائه بسيطًا مع تخفيض السعر سيعمل ، ولكن ربما يجب أن يكون هناك نوع من أداة الفهرسة / التوليد لـ "المستند الرئيسي" أو شيء ما لجمعه معًا والحفاظ عليه متزامنًا. يشبه إلى حد كبير نظام بناء تبعية لآلاف مقتطفات / مستندات تخفيض السعر.

أعتقد Markdown لأجزاء النص. Yaml front-matter أو ملفات json للبيانات الوصفية. معالج مخصص قائم على .NET مع نموذج مكون إضافي قابل للتوسيع لإضافة بناء الجملة بسهولة للأشياء الفاخرة مثل TOC والجداول وما إلى ذلك أو استخدم فقط rst ، وهو مشابه بدرجة كافية لـ Markdown.

فقط اجعل MSDN مفتوح المصدر. إلا إذا كانت فوضى :)

لا تعرف somedave عنك ، لكني أجد صعوبة في العثور على محتوى على MSDN ، خاصة الوثائق المعمارية عالية المستوى على الأطر غير الحالية. يعد وجود الوثائق المرتبطة بالشفرة وجميع المصادر المفتوحة المتاحة وتحت التحكم في الإصدار بمثابة تحسن كبير.

هل نريد حقًا MDSN آخر من Microsoft الجديدة؟ الكثير من الوثائق التي تم إنشاؤها هو مضيعة للوقت. ما تحتاجه هو سرد وأمثلة ، ولكن غالبًا ما ينقص هذا الأمر ترك المعلومات الأساسية التي أمتلكها بالفعل من نظام الكتابة. مع سهولة الوصول إلى المصدر ، يمكننا الآن معرفة ما يفعله شيء ما بالفعل على أي حال. تعتبر المقالات والتوضيحات وأمثلة الاختبار للاستخدام أفضل بكثير خاصة إذا تم إنشاؤها استجابة للطلب مثل أسئلة Stack overflow.

@ danroth27 ، هل تتحدث فقط عن وثائق javadoc / xmldoc ، أم أيضًا التوثيق بشكل عام؟ أي هذا http://www.asp.net/aspnet/overview/authentication-and-identity vs https://msdn.microsoft.com/en-us/library/system.web.mvc.ivalueprovider (v = vs. 118) .aspx؟

دجيني https://github.com/angular/dgeni

بالتأكيد HTML ولكن مع القدرة على استخدامه محليًا - دعنا نقول لتثبيته على IIS المحلي (أو محليًا فقط).

يُرجى البناء على خط أنابيب Sandcastle و SHFB والمساعدة في جعله أجمل (أبسط و "سهل المصدر مفتوح"). يمكن إضافة دعم التأليف markdown (للمحتوى المفاهيمي) والعرض (تم إجراء بعض البدايات بالفعل في هذا الاتجاه).
هناك الكثير من القيمة التجريبية في دعم الأدوات الشائعة المستندة إلى .NET (نصف مليون تنزيل لـ SHFB). تتسرب التعبيرات الاصطلاحية من الأدوات إلى المشروع نفسه. على سبيل المثال ، مع .NET من المفيد حقًا دعم مقتطفات التعليمات البرمجية متعددة اللغات ، بحيث يمكن الحفاظ على VB.NET و F # كلغات قابلة للتطبيق على النظام الأساسي. يقوم Sandcastle والإخراج بنمط MSDN بهذا الأمر الرائع.

تكمن المشكلة في reStructuredText في أنه يشبه Markdown نوعًا ما ، ولكن ليس تمامًا. وهكذا يصبح شكل آخر للتعلم. ينجز SHFB المهمة حاليًا ، لكنها ليست تجربة ممتعة. هناك شيء أفضل من لا شيء و EWoodruff له شكري الدائم لإبقائه على قيد الحياة وتحديثه لفترة طويلة.

من وجهة نظر مطور .NET ، لا تزال هناك حاجة / مطلوب أداة إنشاء مستندات جيدة مفتوحة المصدر لـ .NET. في رأيي ، من الأفضل أن تكون الأداة التي تسمح لكتابة نص طويل باستخدام Markdown لأنه شيء معروف وممتع للاستخدام.

أعلم أن فرق MS ربما ترغب في الحصول على شيء ما وتشغيله لشحن asp.net 5 خارج الباب ، لكن هذا يلامس الألم الطويل الذي يشعر به المطورون.

أحد اقتراحاتي هو العمل مع http://commonmark.org/ لتطوير وحدات العلامات المشتركة والنظر في تحسين شيء مثل https://github.com/Knagis/CommonMark.NET.

بخلاف ذلك ، كن منفتحًا على الأقل لاستبدال نظام المستندات بعد الإصدار الأول حتى لا يعلق المجتمع بشيء لديه الكثير من الاحتكاك لاستخدامه .. مرة أخرى.

أيضا نقطة ألم أخرى. يجب أن تكون المستندات متاحة بتنسيق يمكن استخدامه محليًا. هناك أشخاص يعملون على أنظمة غير متصلة بالإنترنت والتوثيق في وضع عدم الاتصال يعد منقذًا للحياة. اضطررت للعمل في مثل هذه البيئات والوثائق غير المتصلة بالإنترنت لا تقدر بثمن.

ryanbnl نحن نبحث عن حل لكل من الوثائق المرجعية لواجهة برمجة التطبيقات والمحتوى المفاهيمي.

michaelherndon أوافق تمامًا على أن هناك حاجة إلى أداة إنشاء مستندات جيدة مفتوحة المصدر لـ .NET! أنت محق أيضًا في أننا بحاجة إلى الحصول على شيء ما وتشغيله بسرعة لـ ASP.NET. في حالة ظهور وثائق تستند إلى .NET يدعمها المجتمع ، فسنكون بالطبع منفتحين على اعتمادها. نتفق أيضًا على أن وجود طريقة للوصول إلى الوثائق في وضع عدم الاتصال يعد مطلبًا.

حسنًا ، هذا واضح :) بالنسبة إلى مستندات API ، يجدر النظر في doxygen. إنه قوي حقًا ، ويمكنه إنشاء مخططات للفصل (والتي يمكن أن تكون لا تقدر بثمن في مواقف معينة). لقد أجريت مقارنة مفصلة بين doxygen / sandcastle العام الماضي ، يمكنني إرسال نسخة إليك إذا كان ذلك سيساعد؟ يحتوي على الكثير من الأمثلة + دليل التثبيت خطوة بخطوة (doxygen صعب التثبيت) ؛)

يبدو أن إحدى المشكلات تتمثل في الحفاظ على التوثيق مفتوح المصدر حتى يتمكن الآخرون من المساهمة. ثانيًا ، الأداة المستخدمة لإنتاج مثل هذه الوثائق والحفاظ عليها.
لا يمكن أن يكون لدينا أداة مفتوحة المصدر وتسمح بإنشاء html / GHMD للتحميل النهائي. يمكن لأي شخص يحتاج إلى المساهمة استخدام هذه الأداة وتعديل الصفحات بناءً على مستوى الوصول الخاص به على جيثب. يجب أن تكون الأداة مرنة بحيث يمكن استخدامها للمشاريع الصغيرة أو الكبيرة. يمكن أن تكون هذه الأداة عبارة عن امتداد VS يقوم بإنشاء وثائق لأي مشروع ويمكن أن تكون نماذج التوثيق للقوالب الأساسية اختيارية مثل خيارات المصادقة الحالية في المشاريع الجديدة.

farrukhsubhani ، يجب ألا تعتمد الأداة على VS: إذا أردنا أن يستخدم مستخدمو Mac و Linux ASP.NET ويساهمون بها ، يجب أن تكون الأدوات عبر الأنظمة الأساسية ولا تتطلب تثبيتًا ضخمًا.

ألاحظ أن هناك القليل جدًا من التعليقات التوثيقية في المصادر الآن. على الرغم من أنه يختلف من ملف إلى ملف. هل كان هناك قرار بشأن استخدام ذلك كمدخلات للمستندات المرجعية ، أم أن الأمر متروك للمطورين الفرديين؟

بغض النظر عما ستسفر عنه هذه المناقشة ، أود أن أتحدث لصالح على الأقل وجود ذلك في المستقبل ، مع دعم المترجم لإنشاء ملفات XML هذه (أو تنسيق آخر يتم إدخاله في IntelliSense) وتجربة التحرير والتمييز الحالية التي تعتبر لطيفة بشكل خاص مع روزلين في Visual Studio.

ربما يختلف الآخرون بعنف ، لكني لا أحب بشكل خاص تحرير / * * / تعليقات النمط لذلك وسلسلة من * * المحاذاة. من فضلك قل لي لا داعي للقلق ؛)

@ danroth27

فقط بعض الأفكار والشكر مقدمًا على الأقل لقراءتها والتفكير في هذا الأمر.

يبدو النص المعاد هيكلته مثل PITA لإدخال أشياء بسيطة مثل رابط أو عنوان. كنت آخذ تعليقات كود جافادوك أو مجرد لغة ترميز النص الفانيليا فوق هذا في أي يوم من أيام الأسبوع.

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

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

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

check out the _aspnet homepage.

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

أود أن أطلب أن تناقش aspnet داخليًا العمل مع المجتمع على تحديد بعض الأهداف / spes على أداة توثيق .net وربما تقدم بعض الحوافز الإبداعية مثل الاعتراف أو شيء من هذا القبيل. كما أطلب منكم جميعًا مناقشة إعداد المشروع من خلال مؤسسة .NET. يمكن أن يعمل هذا أيضًا كمتدرب لائق / صيف برمجي مثل مشروع لطلاب cs للعمل عليه لأنه على الأرجح سيشمل إنشاء محلل.

هذا ليس موجهًا إليك أو تجاه أي شخص على وجه الخصوص ، ولكن تأخرت دورات التطوير حتى تبدأ الآن في النشر والتفكير في هذا الأمر لأنه يفرض عليك يا رفاق استخدام شيء ناجح ، ولكنه ليس شيئًا يضربك كل السيناريوهات بما في ذلك انخفاض حاجز الدخول.

من الناحية الافتراضية ، قد يكون التحدث مع المجتمع في وقت سابق قد أنتج على الأقل أداة الآن يمكن استخدامها ويمكن بناؤها بالتوازي مع العمل الشاق لفريق aspnet كمثال جيد على نظام aspnet 5 التجريبي.

ومع ذلك ، إذا بدأ هذا الآن ، فقد يكون جاهزًا لاستخدام .NET core 5.

ericwj جميع واجهات برمجة التطبيقات العامة مطلوبة ¹ للحصول على تعليقات مستند XML عليها. ومع ذلك ، في وقت مبكر من المشروع ، قمنا بتخفيف هذا المطلب لأن كتابة الكثير من المستندات على واجهات برمجة التطبيقات التي عرفنا أنها ستتغير بشكل كبير كانت تعتبر جهدًا ضائعًا إلى حد كبير. ومع ذلك ، في جميع الالتزامات من الأشهر القليلة الماضية يجب أن يكون هناك قدر كبير من الوثائق الحالية. لا يزال هناك بالفعل العديد من الثغرات ، ولكن من واجب الفريق تقديم هذه الوثائق. عند تصحيح المستندات ، نميل إلى التركيز على واجهات برمجة التطبيقات الأكثر أهمية التي نعتقد أن المطورين سيصلون إليها ، وننقل المزيد من واجهات برمجة التطبيقات الباطنية إلى الحالة الأقل توثيقًا (التي ما زلنا نأمل في ملؤها يومًا ما).

¹ مطلوب _الهدف_

شيء غير اختياري.
يمكن أن تعني أيضًا شيئًا _is_ اختياريًا في سياق تعليقات مستند XML.

michaelherndon راجع هذا المشروع هو بالفعل جزء من .NET Foundation .

Eilon كان السياق يتحدث عن إضافة أداة توثيق .net وليس aspnet 5.

michaelherndon آه حصلت عليه ، شكرًا!

shanselman @ danroth27 ، لقد أبلغت يوم الجمعة الماضي مديري وقد اتصل هذا المدير بمسؤولي إدارة مجموعة MSDN الرئيسية حول هذا الموضوع. يجب عليهم الاتصال بك بخصوص الوثائق الخاصة بك. طاب يومك.

michaelherndon أوافق على أن صياغة الرأس أكثر تفصيلاً قليلاً. هناك حالة عامة أخرى وهي الارتباط بوظيفة أو صفحة في التوثيق ، حيث يضيء RST:

More Info
=========

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

القيام بشيء مشابه في Markdown:

### 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).

لا أرى فرقًا جوهريًا كبيرًا هنا. يمنحك RST مع Sphinx مجموعة كبيرة من الوظائف المرجعية القيمة التي قد تُفقد أو ترتبط بطريقة غير دلالية بعنوان URL أو مستند HTML في حالة Markdown.

معلومة أخرى مثيرة للاهتمام على طول هذه الأسطر هي هذا المستند حول كيفية كتابة RST و MD بطريقة متوافقة: https://gist.github.com/dupuy/1855764. يدعم Markdown عمومًا رؤوس نمط RST ، بحيث يعمل نمط الرأس عبر كليهما.

يمكنك أيضًا تكوين Sphinx أو أدوات أخرى لفهم بناء جملة Markdown الأساسي مع ملحق إذا كان أداة إيقاف العرض.

أتذكر أنني قلت في لوحة OSS في MVP إرسال منذ حوالي 18 شهرًا أنه لا توجد خيارات جيدة للتوثيق في .NET: stuck_out_tongue_closed_eyes:

ما أود رؤيته حقًا هو طريقة لإنشاء تخفيض السعر أو أول إضافة إلى جدول محتويات من وثائق .NET XML. يمكن بعد ذلك تحميلها في شيء مثل readthedocs أو github wiki.

Sandcastle لديها بالفعل الكثير من التعليمات البرمجية لقراءة وثائق XML .NET وهي قابلة للتوسيع باستخدام أنماط وأنواع مخرجات جديدة. يمكنك البناء على ذلك.

كيف أنظر إلى هذا الخيط وأكتشف النتيجة ، وما إذا كان قد تم اتخاذ قرار ، وإذا كان الأمر كذلك ، فماذا كان؟

https://github.com/aspnet/Docs

لماذا لا تستخدمون DocFX يا رفاق؟

عندما بدأنا في كتابة وثائق ASP.NET 5 ، كان مشروع docfx لا يزال في المراحل الأولى من التطوير. لا يزال Sphinx أكثر نضجًا وإطار عمل توثيق غني بالميزات. علاوة على ذلك ، تقدم Read the Docs حلاً رائعًا لاستضافة الوثائق.

ومع ذلك ، نحن ندعم جهود docfx كحل توثيق لـ .NET ومن المثير أن نرى أن docfx أصبح الآن مفتوح المصدر! نحن نخطط بالفعل لاستخدام docfx للتوثيق المرجعي لواجهة برمجة التطبيقات ونتوقع الانتقال إلى docfx عندما ينضج.

يبدو أنه من العار الذهاب في اتجاهين مختلفين خارج البوابة عندما يبدو أن docfx هو ما تستخدمه MSDN ، على الأقل باستخدام السمات المضمنة.

simonmurdock docfx لا يدعم (حتى الآن) إنشاء مستندات غير متصلة بالإنترنت ، مثل PDF

Yeahcocowalla أنا في حالة تغير مستمر حول حالة الاتحاد مع التوثيق. أنا الآن أكتب مقالاتي في أبو الهول ، ولكن لا توجد طريقة رائعة لإنشاء مستندات API متكاملة لأبو الهول.

الخطة الحالية هي Sphinx لجميع المقالات وموقع منفصل لإخراج DocFX ، حتى يبدو Sphinx ApiDocs أفضل قليلاً.

simonmurdock إليك ما نقوم به حاليًا لإنشاء مستندات مرجع API لـ ASP.NET باستخدام مزيج من docfx وامتداد Sphinx autoapi : https://github.com/aspnet/apidocs. لا يزال الأمر صعبًا بعض الشيء ، لكننا نعمل مع أشخاص Read the Docs على مجموعة من التحسينات.

@ danroth27 لقد كانت العديد من الأصوات لصالح RsT ، ولكن في النهاية اخترت MD؟ عندما أقوم بالنقر فوق تحرير في أي صفحة في https://docs.microsoft.com/en-us/aspnet/core/ ، أرى ملف MD المصدر على GitHub.
فلماذا MD؟

كنا نستخدم RST و http://readthedocs.com لبعض الوقت من أجل مستندات ASP.NET Core و EF Core ، ولكن مؤخرًا قامت Microsoft ببناء بنيتها التحتية الخاصة للمستندات على http://docs.microsoft.com ، لذلك انتقلنا إلى تتماشى مع ذلك. في حين أن تخفيض السعر ليس ناضجًا لغة توثيق مثل reStructuredText مألوف أكثر لجمهور أوسع. حتى قراءة المستندات يدعم كلا التنسيقين لهذا السبب.

@ danroth27 هل هذا يعني أن Microsoft قد أنشأت منشئ / محرك توثيق غير مفتوح المصدر خاص بها يستخدم تخفيض السعر؟ ما الذي يبقى خلف https://docs.microsoft.com؟

هل هذا يعني أن Microsoft قد أنشأت منشئ / محرك وثائق غير مفتوح المصدر خاص بها يستخدم تخفيض السعر؟

لا. محرك المستند الذي يقف وراء https://docs.microsoft.com هو DocFX وهو مبني على .NET وهو مفتوح المصدر بالكامل. إنها تستخدم تخفيض السعر لشكلها.

مرحبا

قد أتأخر قليلاً في نشر هذا.

أنا فقط أتساءل عما إذا كان هناك API أو إطار عمل أو أداة تتيح لنا إنشاء موقع توثيق مثل الموقع https://docs.microsoft.com؟ أنا شخصياً أحب الطريقة التي يتم بها تقديم وثائق Microsoft ، حيث ذكر @ danroth27 أن DocFX هو المحرك الذي تم استخدامه ، أريد فقط معرفة ما إذا كان الموقع نفسه شيئًا يتم تنفيذه من الأساس أم أن هناك قالبًا أو حزمة يمكننا القيام بها تستخدم لتوليد نفس الشكل والمظهر؟ ليس بالضبط نفس الشيء ولكن يمكننا تعديله :)

شكرا!
جود القيزا.

كلما قرأت أكثر عن DocFx ، زاد إعجابي به - سأجربه قريبًا.

كيف يمكننا إنشاء موقع التوثيق الخاص بنا مثل https://docs.microsoft.com/ داخليًا دون إعادة اختراع العجلة؟ نحن نستخدم readthedocs المستضاف لمستندات python و doxygen مستضاف لمستندات c / c ++.

ما هي أفضل طريقة للحصول على جميع مستندات API تحت سقف واحد؟ من خلال قراءة هذا الموضوع ، يبدو أن العديد من الأشخاص يستخدمون sphinx / readthedocs ولكن كيف تقوم بتحويل وثائق XML الخاصة بك إلى التنسيق الصحيح لهذه الأدوات؟