Aspnetcore: Welches Format sollten wir für die ASP.NET 5-Dokumentation verwenden?

http://shfb.codeplex.com

Oder machen Sie einfach etwas ganz Neues.

Ein guter Präprozessor, der GH Markdown generiert, wäre ausgezeichnet.

+1 für Markdown (oder GitHub Flavored Markdown). Es mag einige Funktionen fehlen, aber es ist ziemlich bekannt und sehr einfach zu erlernen und zu verwenden. Ich denke, es hängt von der endgültigen Entscheidung ab, wo es gehostet wird, da Sie einige Optionen erwähnt haben.

Hallo, Daniel,
Danke für Ihren Beitrag.
Als Junior-Entwickler finde ich, dass es einfach ist, Dokumente als Titel in der Seitenleiste zu organisieren, ähnlich wie hier http://rustbyexample.com/
(MEINER BESCHEIDENEN MEINUNG NACH)

-1 auf die Herstellung von etwas ganz Neuem.
+1, um an etwas Vorhandenem zu arbeiten und wenn möglich zu verbessern.

@danroth27 Können Sie uns etwas mehr Details über Ihre Dokumentationsanforderungen mitteilen und welche Funktionen eines ausgereiften Dokumentationssystems Sie benötigen?

Ich denke, dass es zu einfach ist, "Markdown verwenden" zu sagen.

Markdown ist eine DSL für HTML. Das ist alles. Würden Sie wirklich sagen: „Docs ist ein gelöstes Problem, verwenden wir HTML!“

Wir brauchen ein aktuelles Dokumentationssystem wie Sphinx.

• Markdown kann kein Inhaltsverzeichnis generieren.
• Markdown kann nicht zwischen Themen verlinken (Sie müssen die Links manuell erstellen)
• Markdown kann Dinge wie mehrsprachige Unterstützung oder Unterstützung mehrerer Versionen nicht leisten.

Ich unterstütze Read The Docs von @ericholscher , insbesondere aber Sphinx und reStructuredText.

Oder verwenden Sie Doxygen und vNext wird niemals veröffentlicht ;)

Was ist mit etwas Ähnlichem wie Roslyn oder AngularJS? http://source.roslyn.codeplex.com/ https://docs.angularjs.org/api

Markdown funktioniert sehr gut für die meisten anderen Projekte auf GitHub. +1 für Markdown.

@shanselman , relative Links?

Ich denke, die Verwendung von Sphinx würde funktionieren.
@issafram Beispiele hier:
http://sphinx-doc.org/
https://docs.python.org/3/tutorial/index.html

@akoeplinger Wir hätten gerne etwas, aus dem wir einfach Inhaltsverzeichnisse erstellen und einfach seitenübergreifend verlinken können. Wir möchten auch etwas, das eine Vielzahl von Dokumentformaten generieren kann, darunter HTML, PDF und ePub. Die Dokumente sollten auch auf Mobilgeräten lesbar sein.

@issafram Markdown ist großartig, wenn Ihre Dokumente hundert Seiten umfassen, höchstwahrscheinlich weniger. Aber Tausende von Seiten und ineinandergreifende Inhaltsverzeichnisse? Anhänge aktuell halten? Verknüpfen von ASP.NET- und .NET-Dokumenten? Es wird ein Durcheinander.

Denken Sie daran, wenn Sie möchten, dass dies wirklich Open Source ist und somit etwas, das Beiträge fördert, dass das System so einfach wie möglich sein muss, ohne Lernkurve. Markdown kann kein ToC selbst generieren, aber relativ einfacher Code kann ToC aus Markdown generieren.
Wir bei Orchard sind sehr zufrieden mit unserem System, das Markdown auf Github plus eine Azure-Site mit sehr wenig Code (für Lucene-Indizierung und -Suche sowie ToC-Generierung) ist, das jedes Mal automatisch aktualisiert wird, wenn das Repo gepusht wird. Supereinfache, vertraute Werkzeuge.
Das einzige, was mir daran nicht gefällt, ist das Fehlen von Metadaten (wir extrahieren die Titel aus Dateinamen), aber auch dafür gibt es Lösungen, wie Jeckylls YAML-Header (unterstützt von Github) oder mein eigenes Snippable-Format.

@issafram Das funktioniert zum Beispiel bei riesigen Codebasen mit VIELEN Dokumenten und Refactoring nicht gut. Benennen Sie eine Klasse und _bye bye_ relative Links um.

_edit_: Ich komme zu spät zum Spiel :P

Ich freue mich zu hören, dass die ASP.NET-Dokumentation Tausende von Seiten umfassen wird ;) Trotzdem, KISS.

@bleroy Werfen Sie einen Blick auf dieses http://read-the-docs.readthedocs.org/en/latest/ und das rST, das es geschafft hat. https://github.com/rtfd/readthedocs.org/blob/master/docs/index.rst

Klar, das ist toll. Geben nur unsere Erfahrung weiter. Ich verstehe, dass Sie in einer anderen Größenordnung sind.

rST ist hier die beste Option, zum Anfassen. Da es sich um ASP.NET handelt, hat es wahrscheinlich höchste Priorität, etwas zu haben, das intelligent genug ist, um seine Indizes zu aktualisieren (vom ToC- oder sogar vom Standpunkt der Klassenauflistung).

Idealerweise würde ich etwas im Build-Workflow ausführen, um all diese .XML-Dateien zu erfassen, die aus den Binärdateien generiert wurden, und sie dann durch einen Prozessor leiten, um die Dateien zu generieren, die dann auf einem Server veröffentlicht werden. Die genauen Werkzeuge .... Ich habe keine Ahnung. Viele wurden erwähnt. Ich würde empfehlen, ein eigenes zu bauen und es als Open Source zu öffnen. Ja ja ... Build vs. Buy-Debatte, aber ich hasse es, Tools zu verwenden, die nicht verwaltete Ressourcen haben, wie einige der oben genannten. Wie auch immer, das klingt ideal ... Sie haben wahrscheinlich Budget- und Zeitbeschränkungen und was nicht.

@issafram Wenn Sie alle Sphinx/RTD verwenden, könnte etwas in der Art von Breathe ein praktikabler Ansatz sein: http://breathe.readthedocs.org/en/latest/ - es ist die Integration mit Sphinx & Doxygen, die die verwendet Doxygen-XML-Dateien.

@issafram Klingt für mich, als würdest du SHFB beschreiben ... (Eigentlich Sandcastle , SHFB macht es nur angenehmer zu benutzen: P)

Ja, Sie benötigen einen Präprozessor/Postprozessor, Sie können die Relativitätstheorie innerhalb des Dokuments mit GHMD für TOC verknüpfen. Für unsere Projekte haben wir unsere eigenen erstellt, die im Wesentlichen .Net-Dokument-XML und Konventionsbasiert mit Beispielcode und anderen statischen Inhalten, die in MD geschrieben sind, zusammengeführt haben. Endergebnis ist HTML.

Code und redaktionelle statische Inhalte in MD zu haben, würde es einfach machen, PRs zu machen. Was mir an Markdown als Quellformat gefällt, ist, dass es sauberer als HTML, XML usw. ist. Macht die Prüfung einfach und eignet sich gut für die Quellcodeverwaltung.

Wir brauchen ein sauberes und einfaches konventionsbasiertes Dokumentationstool für .Net, ich habe keins gefunden, wenn es eines gibt, würde ich gerne informiert werden. Und tragen gerne dazu bei.

Was die Wartbarkeit und Verlinkung über Projekte angeht. Intersphinx ist eine leistungsstarke Möglichkeit, dies auf semantische Weise zu tun. Es ermöglicht Ihnen, alle Referenzen (sei es Code oder Prosa) zu katalogisieren und explizit projektübergreifend darauf zu verlinken.

Dokumente hier: http://sphinx-doc.org/latest/ext/intersphinx.html

Dies ist die Art von Funktionalität, die so etwas wie Markdown in keiner Weise hat, die ich kenne.

Einverstanden, dass Markdown nicht die beste Lösung ist, aber im Moment brauchen wir eine einfache Lösung. Com'on, wir sind Entwickler, also können wir dies bei Bedarf erweitern. Github unterstützt Markdown, VSO unterstützt seit kurzem Markdown aus der Codeansicht. Brauchen wir wirklich eine Debatte? Entschuldigung, wenn ich zu direkt bin.

Abschlag +1

@ctsni Ich gebe zu, Markdown _fühlte_ sich auf den ersten Blick/Gedanken als die beste Wahl an. Aber je mehr ich darüber nachdenke, desto mehr fühlt es sich an, als würden wir versuchen, einen quadratischen Stift in ein rundes Loch zu hämmern.

Ich habe zugegebenermaßen keine gute Alternative, also entschuldige ich mich dafür, dass ich nicht wirklich viel beigetragen habe, aber selbst wenn ich Markdown erweitere, habe ich nicht das Gefühl, dass wir am Ende mit etwas dem gleichen hübschen, sauberen und ordentlichen Markdown enden würden, wie wir es jetzt _gegeben haben Bedarf_.

Es hört sich so an, als ob Sie die vorhandene MSDN-Dokumentation in einem Open-Source-Format replizieren möchten? Ist das fair? Sie benötigen eine Lösung zur Handhabung von Übersichtsbeschreibungen, Tutorials, Codebeispielen und API-Dokumentation? Oder ist es eine Teilmenge davon?

Ich bin nicht davon überzeugt, dass es eine Lösung gibt, eher eine Sammlung von Tools, deren Ergebnisse kombiniert werden können. Ich kann sehen, was ReadTheDocs tut - mehrere Quellen in eine zusammenhängende Dokumentation ziehen. Markdown ist also eine gültige Antwort auf einen Teil der Lösung (dh die Beschreibungen und Tutorials), aber nicht das vollständige Bild?

Offene Frage: Ist es möglich, Anhänge und Inhaltsverzeichnis direkt aus Markdown zu extrahieren? Scheint mir nicht zu schwierig? Ich bin voreingenommen. Ich habe nicht an einem System mit Tausenden von Seiten gearbeitet ... Entschuldigung @shanselman , ich kann wirklich keine Weisheit beitragen, die über das hinausgeht, was ich weiß.

@craignicol Alles andere als die aktuelle MSDN-Dokumentation wäre für mich eine große Enttäuschung. Ich sage jedem immer, dass einige der besten Dokumentationen (in Bezug auf Struktur, Wortlaut und alles darüber) auf MSDN zu finden sind. Ich habe viele Dokumentationen gesehen, aber die meisten, wenn nicht alle, kommen nicht einmal annähernd an die "MSDN-Qualität" heran (IMHO natürlich). Abgesehen davon: Ein großer Faktor ist natürlich, dass sich die Leute hinter den MSDN-Dokumenten so gut um den eigentlichen _Inhalt_ von MSDN kümmern; Struktur, Layout, Design und What-have-you kommen erst an zweiter Stelle.

Vielleicht tangential, aber es wäre sehr schön, so etwas wie Bindestrich zu haben. Die Webentwicklung entwickelt sich so schnell und neue Technologien beeinflussen sich gegenseitig, dass ich hier und da nach Informationen google. In der Lage zu sein, auf alles an einem einzigen geschlossenen Ort zuzugreifen, der über einige Tastenanschläge aufgerufen werden kann, ist unglaublich hilfreich. Es gibt einen ähnlichen Versuch http://zealdocs.org/ für Linux und Windows.

@craignicol Einverstanden, das Ziel ist es, MSDN-Qualitätsdokumente zu haben, die Open Source und einfacher zu warten und auf dem neuesten Stand zu halten sind.

@ciriarte Es gibt Unterstützung für die Übersetzung von Sphinx-Dokumenten in Dash: https://pypi.python.org/pypi/doc2dash – Wir haben uns die automatische Erstellung von Dash-Sets auf RTD.org angesehen, haben sie aber derzeit nicht implementiert.

Ich denke, @shanselman hat es oben am besten ausgedrückt - Markdown ist nicht die Antwort, genauso wenig wie HTML, Word oder .txt die Antwort wären. Markdown ist in erster Linie eine Präsentationsbeschreibung - was benötigt wird, ist etwas, um den Markdown zu generieren (oder HTML, Word-Dokument, .txt-Datei usw.)

Ich denke, meine Frage wäre, woher kommt dieser Inhalt? Soll es handschriftlich sein? Automatisch aus dem Code generiert? Eingebettet in Kommentare?

Ich stimme mit @craignicol einer Sammlung von Tools zum Zusammenführen von automatisch generierten Inhalten mit "statischen" GH-Markdown-Seiten für künstliche Muster und redaktionelle Inhalte zu, die in Assembler-XML nicht verfügbar sind. Das Ergebnis könnte dann statisches HTML auf GHPages, PDF oder was auch immer sein.
Der Präprozessor könnte verwaiste statische Inhalte erkennen, wenn der Code umbenannt/umgestaltet wird, dh
Sprachunterstützung könnten grundsätzlich optionale Ordner mit der gleichen Struktur wie neutral sein. Nicht übersetzte Dokumente könnten dann auf neutral zurückgreifen oder durch die Bing-Übersetzung gehen.

Rückblickend auf den ursprünglichen Vorschlag würde @danroth27 bezüglich Markdown für Format und readthedocs für Build zustimmen. Danke.

Die Flexibilität von readthedocs.org + Sphinx kann eine Äquivalenz mit MSDN ermöglichen, wenn dies nicht möglich ist.

@ciriarte Das könnte wahrscheinlich auch mit exportierbaren Archiven für den MSDN-Reader unterstützt werden.

@jalcine @ericholscher klingt fantastisch.

@RobThree Ich hoffe, das Team, das derzeit die Dokumente pflegt, kann davon überzeugt werden, auf das neue Format umzusteigen, sonst lohnt sich diese Übung nicht.

@ctsni es ist möglich - ich habe einen Markdown-ToC-Parser in Python geschrieben, der eine Liste von Dateien nimmt und ein ToC generiert. Der knifflige Teil besteht darin, die Quelldateien mit Anmerkungen zu versehen, damit der Parser weiß, was er extrahieren muss, um das Inhaltsverzeichnis und die Anhänge zu generieren. Das Zwischenformat, ob Markdown oder rST, spielt keine Rolle, entscheidend sind die richtigen Metadaten.

Wenn man sich die MSDN-Dokumentation ansieht, sind die beiden wichtigsten Metadatenteile, die für das Hyperlinking am wichtigsten sind, die API-Hooks, um das Durchlaufen des Codes zu ermöglichen, und die konzeptionellen Hooks (z. B. Sicherheit), die ein Thema erstellen, das die API umfasst, die Tutorials, und die Architekturinformationen. Wenn der API-Teil richtig gemacht wird, bin ich sicher, dass der Rest des Inhalts angepasst werden kann. Ich mag die Idee von Dash, aber ich denke, ReadTheDocs und Sphinx kommen dem, was ich an MSDN mag, am nächsten, aber ich denke, sie müssen angepasst werden, um die reichhaltige Themen- und Tutorialstruktur von MSDN zu handhaben.

Ich wundere mich über dieses ganze Konzept. Ich meine, ich liebe die Idee, die Dokumentationskette offen zu beziehen und die Community einzubeziehen, aber es außerhalb von MSDN zu tun, macht mich irgendwie verrückt. Seit den Anfängen von .NET, die wie es scheint (und gewesen sein könnten) sind wir zu MSDN gegangen, um kanonische Referenzen für alle Microsoft-APIs zu erhalten. Von WinForms bis WebForms ist alles an einem Ort, schön querverwiesen und einheitlich formatiert. Ich kann nicht umhin, mich zu fragen, ob das, was aus diesem Unterfangen gewonnen wird, genug Nutzen bringt, um die Fragmentierung und den Verlust an Konsistenz aufzuwiegen. Nicht zu sagen, dass es sich nicht absolut lohnen wird, und vermutlich haben diese Diskussionen bereits stattgefunden, aber zum Nachdenken.

+1 für Sphinx

Ich mag das readthedocs-Format und die Tools wirklich und sie funktionieren sehr gut für viele Projekte. Erfinden Sie das Rad nicht neu. Abschlag ist in Ordnung. Ich denke, wenn Sie es nicht mit Markdown beschreiben können, versuchen Sie, etwas zu Kompliziertes zu tun. Ich für meinen Teil würde gerne einen Beitrag leisten, wenn das Format und die Friktion gering sind. Das MSDN-Wiki war auf dem Weg dorthin, aber das meiste davon war geschlossen und wurde zu einer öden Einöde alter Inhalte. Die PHP-Community scheint es mit ihrem Doc-System ziemlich gut zu machen (obwohl ihre Kommentare manchmal in Kaninchenlöchern landen). Ich denke, es wird funktionieren, es mit Markdown einfach zu halten, aber es muss wahrscheinlich eine Art Indizierungs- / Generierungstool für das "Master-Dokument" oder etwas geben, um es zusammenzuführen und synchron zu halten. Fast wie ein Abhängigkeits-Build-System für Tausende von Markdown-Snippets/Dokumenten.

Ich denke Markdown für Textfragmente. Yaml-Frontmatter oder JSON-Dateien für Metadaten. Benutzerdefinierter .NET-basierter Prozessor mit erweiterbarem Plugin-Modell zum einfachen Hinzufügen von Syntax für ausgefallene Dinge wie Inhaltsverzeichnis und Tabellen usw. Oder verwenden Sie einfach first, ähnlich genug wie Markdown.

Machen Sie MSDN einfach zu Open Source. Es sei denn, es ist ein Durcheinander :)

@somedave weiß nicht, wie es Ihnen geht, aber ich fand es immer schwieriger, Inhalte auf MSDN zu finden, insbesondere Architekturdokumentation auf hoher Ebene zu nicht aktuellen Frameworks. Die mit dem Code verknüpfte Dokumentation und alle verfügbaren Open-Source- und Versionskontrollen sind eine enorme Verbesserung.

Wollen wir wirklich ein weiteres MDSN von New Microsoft? Ein Großteil der generierten Dokumentation ist Zeitverschwendung. Was es brauchte, waren Erzählungen und Beispiele, aber so oft fehlten diese und es blieben nur grundlegende Informationen, die ich bereits aus dem Typensystem habe. Mit einfachem Zugriff auf die Quelle können wir jetzt sowieso herausfinden, was etwas wirklich bewirkt. Artikel, Erklärungen und Testanwendungsbeispiele sind viel besser, insbesondere wenn sie als Reaktion auf Nachfrage erstellt werden, z. B. Stapelüberlauffragen.

@danroth27 , sprichst du nur von javadoc/xmldoc-Dokumentation oder auch von Dokumentation im Allgemeinen? Dh diese 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?

Dgeni https://github.com/angular/dgeni

Definitiv HTML, aber mit der Möglichkeit, es lokal zu verwenden - sagen wir, es auf dem lokalen IIS (oder nur lokal) zu installieren.

Bitte bauen Sie auf der Sandcastle- und SHFB-Pipeline auf und helfen Sie, sie schöner zu machen (einfacher und 'Open-Source-freundlich'). Unterstützung für Markdown-Authoring (für konzeptionelle Inhalte) und Rendering kann hinzugefügt werden (einige Ansätze in diese Richtung wurden bereits gemacht).
Die Unterstützung der beliebten (eine halbe Million Downloads für SHFB) .NET-basierten Tools ist von großem Dogfood-Wert. Redewendungen dringen aus den Tools in das Projekt selbst ein. Beispielsweise ist es bei .NET sehr wertvoll, mehrsprachige Codeausschnitte zu unterstützen, sodass VB.NET und F# als funktionsfähige Sprachen auf der Plattform beibehalten werden können. Sandcastle und die Ausgabe im MSDN-Stil machen das großartig.

Das Problem bei reStructuredText ist, dass es ähnlich wie Markdown ist, aber nicht ganz. Somit wird es zu einem weiteren Lernformat. SHFB erledigt derzeit die Arbeit, aber es ist keine angenehme Erfahrung. Etwas ist besser als nichts, und EWoodruff gilt mein ewiger Dank dafür, dass Sie dies so lange am Leben erhalten und aktualisiert haben.

Aus Sicht eines .NET-Entwicklers wird immer noch ein wirklich gutes Opensource-Tool zur Generierung von Dokumenten für .NET benötigt / gesucht. Meiner Meinung nach ist es vorzugsweise ein Tool, das es ermöglicht, lange Texte mit Markdown zu schreiben, weil es etwas ist, das bekannt ist und Spaß macht.

Ich weiß, dass die MS-Teams wahrscheinlich etwas zum Laufen bringen wollen, um asp.net 5 aus der Tür zu liefern, aber dies berührt einen langjährigen Schmerz, den Entwickler empfinden.

Einer meiner Vorschläge ist, mit http://commonmark.org/ zusammenzuarbeiten, um Commonmark-Module zu entwickeln und etwas wie https://github.com/Knagis/CommonMark.NET zu verbessern.

Ansonsten sollten Sie zumindest offen dafür sein, das Dokumentensystem nach der ersten Veröffentlichung zu ersetzen, damit die Community nicht mit etwas festsitzt, das viel Reibungspunkte in der Verwendung hat ... schon wieder.

Auch ein weiterer Schmerzpunkt. Die Dokumente sollten in einem Format verfügbar sein, das lokal verwendet werden kann. Es gibt Leute, die an Systemen arbeiten, die nicht mit dem Internet verbunden sind, und die Offline-Dokumentation ist ein Lebensretter. Ich musste in solchen Umgebungen arbeiten und Offline-Dokumentationen sind von unschätzbarem Wert.

@ryanbnl Wir suchen nach einer Lösung sowohl für die API-Referenzdokumentation als auch für konzeptionelle Inhalte.

@michaelherndon Ich stimme voll und ganz zu, dass ein gutes Open-Source-Tool zur Generierung von Dokumenten für .NET benötigt wird! Sie haben auch Recht, dass wir schnell etwas für ASP.NET zum Laufen bringen müssen. Sollte eine von der Community unterstützte .NET-basierte Dokumentation entstehen, wären wir natürlich bereit, sie zu übernehmen. Wir stimmen auch zu, dass eine Möglichkeit, offline auf die Dokumentation zuzugreifen, eine Voraussetzung ist.

Okay, das ist klar :) Für API-Dokumente lohnt sich ein Blick auf doxygen. Es ist wirklich leistungsfähig und kann Klassendiagramme erstellen (die in bestimmten Situationen von unschätzbarem Wert sein können). Ich habe letztes Jahr einen ausführlichen Vergleich von Doxygen/Sandcastle gemacht, kann ich Ihnen eine Kopie schicken, wenn es helfen würde? Es enthält viele Beispiele + eine Schritt-für-Schritt-Installationsanleitung (Doxygen ist schwierig zu installieren) ;)

Ein Problem scheint darin zu bestehen, die Dokumentation Open Source zu halten, damit andere etwas beitragen können. Zweitens ist das Werkzeug, das verwendet wird, um eine solche Dokumentation zu erstellen und zu pflegen.
Können wir nicht ein Open-Source-Tool haben, das HTML/GHMD für den endgültigen Upload generiert? Jeder, der einen Beitrag leisten muss, kann dieses Tool verwenden und Seiten basierend auf seiner Zugriffsebene auf github ändern. Das Tool sollte flexibel sein, damit es für kleine oder große Projekte verwendet werden kann. Dieses Tool kann eine VS-Erweiterung sein, die eine Dokumentation für jedes Projekt generiert, und eine Beispieldokumentation für grundlegende Vorlagen kann optional sein, wie aktuelle Authentifizierungsoptionen in neuen Projekten.

@farrukhsubhani Das Tool sollte wahrscheinlich nicht von VS abhängen: Wenn wir möchten, dass Mac- und Linux-Benutzer ASP.NET verwenden und dazu beitragen, müssen die Tools plattformübergreifend sein und sollten keine große Installation erfordern.

Mir ist aufgefallen, dass es jetzt sehr wenige Dokumentationskommentare in den Quellen gibt. obwohl es von Datei zu Datei unterschiedlich ist. Gab es eine Entscheidung, dies als Eingabe für die Referenzdokumente zu verwenden, oder lag es an einzelnen Entwicklern?

Was auch immer diese Diskussion ergibt, ich würde mich dafür aussprechen, dass wir das zumindest in Zukunft noch haben, mit Compiler-Unterstützung zum Erstellen dieser XML-Dateien (oder einem anderen Format, das sich in IntelliSense einfügt) und der heutigen Bearbeitungs- und Hervorhebungserfahrung, die besonders nett ist Roslyn in Visual Studio.

Vielleicht sind andere heftig anderer Meinung, aber ich mag es besonders nicht, Kommentare im /* */-Stil dafür und eine Reihe von ausgerichteten * zu bearbeiten. Bitte sagt mir, dass ich mir keine Sorgen machen muss ;)

@danroth27

Nur ein paar Gedanken und danke im Voraus, dass Sie zumindest gelesen und darüber nachgedacht haben.

Umstrukturierter Text scheint wie PITA zu sein, um einfache Dinge wie einen Link oder eine Überschrift einzufügen. Ich würde an jedem Tag der Woche Javadoc-Code-Kommentare oder einfach Vanilla-HTML dazu nehmen.

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

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

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

check out the _aspnet homepage.

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

Ich möchte darum bitten, dass das Aspnet intern die Zusammenarbeit mit der Community bespricht, um einige Ziele / Spes für ein .net-Dokumentationstool festzulegen und vielleicht einige kreative Anreize wie Anerkennung oder etwas in dieser Richtung bereitzustellen. Ich bitte Sie auch alle, die Einrichtung des Projekts über die .NET Foundation zu besprechen. Dies könnte auch als anständiges Praktikum / Summer of Code-ähnliches Projekt dienen, an dem CS-Studenten arbeiten können, da es höchstwahrscheinlich die Erstellung eines Parsers beinhalten würde.

Dies richtet sich nicht an Sie oder irgendjemanden im Besonderen, aber es ist spät in den Entwicklungszyklen, um jetzt damit zu beginnen, darüber zu posten und darüber nachzudenken, da es Sie in die Ecke zwingt, etwas zu verwenden, das funktioniert, aber nicht etwas ist, das trifft alle Szenarien einschließlich niedriger Eintrittsbarrieren.

Hypothetisch gesprochen, könnte ein früheres Gespräch mit der Community inzwischen zumindest ein Tool hervorgebracht haben, das brauchbar gewesen wäre und parallel zu all der harten Arbeit des Aspnet-Teams als gutes Beispiel für ein Dogfooding von Aspnet 5 hätte gebaut werden können.

Davon abgesehen, wenn dies jetzt gestartet würde, könnte es für die Verwendung von beispielsweise .NET Core 5 bereit sein.

@ericwj Alle öffentlichen APIs müssen ¹ XML-Dokumentkommentare enthalten. Zu Beginn des Projekts haben wir diese Anforderung jedoch gelockert, da das Schreiben vieler Dokumente zu APIs, von denen wir wussten, dass sie sich erheblich ändern würden, als weitgehend verschwendete Mühe angesehen wurde. In allen Commits der letzten Monate sollte jedoch eine beträchtliche Menge an Dokumentation vorhanden sein. Es gibt zwar noch viele Löcher, aber es ist eine Pflicht des Teams, diese Dokumentation zu liefern. Beim Patchen der Dokumentation neigen wir dazu, uns auf die wichtigeren APIs zu konzentrieren, auf die Entwickler unserer Meinung nach zugreifen werden, und esoterischere APIs auf einen weniger dokumentierten Status zu verweisen (den wir immer noch hoffen, eines Tages auszufüllen).

¹ erforderlich _Adjektiv_

Etwas, das nicht optional ist.
Kann auch etwas bedeuten, das im Kontext von XML-Doc-Kommentaren optional ist.

@michaelherndon Übrigens ist dieses Projekt bereits Teil der .NET Foundation .

@Eilon der Kontext sprach davon, ein .net-Dokumentationstool hinzuzufügen, nicht aspnet 5.

@michaelherndon Ah verstanden, danke!

@shanselman @danroth27 , ich habe letzten Freitag meinen Manager informiert und dieser hat die PMs der MSDN Principal Group über diesen Thread kontaktiert. Sie sollten sich bezüglich Ihrer Dokumentationsangelegenheit mit Ihnen in Verbindung setzen. Einen schönen Tag noch.

@michaelherndon Ich stimme zu, dass die Header-Syntax etwas ausführlicher ist. Ein weiterer allgemeiner Fall ist das Verlinken auf eine Funktion oder Seite in der Dokumentation, wo RST glänzt:

More Info
=========

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

Etwas Ähnliches in Markdown tun:

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

Ich sehe hier keinen großen grundsätzlichen Unterschied. RST mit Sphinx bietet Ihnen eine große Auswahl an wertvollen Referenzfunktionen, die im Markdown-Fall verloren gehen oder auf nicht-semantische Weise mit einer URL oder einem HTML-Dokument verknüpft würden.

Ein weiterer interessanter Leckerbissen in diese Richtung ist dieses Dokument darüber, wie man RST und MD auf kompatible Weise schreibt: https://gist.github.com/dupuy/1855764. Markdown unterstützt im Allgemeinen Header im RST-Stil, sodass der Header-Stil für beide funktioniert.

Sie können auch Sphinx oder andere Tools konfigurieren, um die grundlegende Markdown-Syntax mit einer Erweiterung zu verstehen, wenn dies ein Show-Stopper ist.

Ich erinnere mich, dass ich vor etwa 18 Monaten im OSS-Panel bei MVP Submit gesagt habe, dass es keine guten Optionen für die Dokumentation in .NET gebe :stuck_out_tongue_closed_eyes:

Was ich wirklich gerne sehen würde, ist eine Möglichkeit, Markdown oder First plus ein Inhaltsverzeichnis aus der .NET XML-Dokumentation zu generieren. Das kann dann in so etwas wie readthedocs oder github wiki geladen werden.

Sandcastle verfügt bereits über eine Menge Code zum Lesen der .NET-XML-Dokumentation und ist mit neuen Stilen und Ausgabetypen erweiterbar. Darauf könnte man aufbauen.

Wie schaue ich mir diesen Thread an und finde heraus, was die Schlussfolgerung war, ob eine Entscheidung getroffen wurde und wenn ja, welche?

https://github.com/aspnet/Docs

Warum nutzt ihr nicht DocFX?

Als wir mit dem Schreiben von Dokumentation für ASP.NET 5 begannen, befand sich das docfx-Projekt noch in der frühen Entwicklungsphase. Sphinx ist immer noch ein viel ausgereifteres und funktionsreicheres Dokumentations-Framework. Darüber hinaus bietet Read the Docs eine wirklich gute Dokumentations-Hosting-Lösung.

Allerdings unterstützen wir die Bemühungen von docfx als Dokumentationslösung für .NET und es ist spannend zu sehen, dass docfx jetzt Open Source ist! Wir planen bereits, docfx für die API-Referenzdokumentation zu verwenden, und gehen davon aus, zu docfx überzugehen, wenn es ausgereift ist.

Scheint nur eine Schande zu sein, zwei verschiedene Richtungen aus dem Tor zu gehen, wenn docfx das zu sein scheint, was MSDN verwendet, zumindest wenn man sich an die integrierten Themen hält.

@simonmurdock docfx unterstützt (noch) nicht die Generierung von Offline-Dokumenten wie PDF

Ja @cocowalla Ich bin in ewigem Fluss über den Stand der Gewerkschaft mit Dokumentation. Ich schreibe jetzt meine Artikel in Sphinx, aber keine wirklich nette Möglichkeit, Sphinx-integrierte API-Dokumente zu generieren.

Der aktuelle Plan ist Sphinx für alle Artikel und eine separate Site für die Ausgabe von DocFX, bis die Sphinx ApiDocs etwas besser aussehen.

@simonmurdock Folgendes tun wir derzeit, um API-Referenzdokumente für ASP.NET mit einer Kombination aus docfx und der Sphinx -Autoapi- Erweiterung zu generieren: https://github.com/aspnet/apidocs. Es ist immer noch ein bisschen holprig, aber wir arbeiten mit den Read the Docs-Leuten an einer Reihe von Verbesserungen.

@danroth27 So viele Stimmen waren für RsT, aber letztendlich hast du dich für MD entschieden? Wenn ich auf einer beliebigen Seite in https://docs.microsoft.com/en-us/aspnet/core/ auf BEARBEITEN klicke, sehe ich die MD-Quelldatei auf GitHub.
Warum also MD?

Wir haben RST und http://readthedocs.com eine Zeit lang für die ASP.NET Core- und EF Core-Dokumentation verwendet, aber kürzlich hat Microsoft seine eigene Dokumentationsinfrastruktur unter http://docs.microsoft.com aufgebaut, also sind wir zu gewechselt sich daran ausrichten. Markdown ist zwar keine so ausgereifte Dokumentationssprache wie reStructuredText, aber einem breiteren Publikum bekannter. Auch Read the Docs unterstützt aus diesem Grund beide Formate.

@danroth27 Bedeutet das, dass Microsoft seinen eigenen Generator/Engine für Nicht-Open-Source-Dokumentation entwickelt hat, der Markdown verwendet? Was bleibt hinter https://docs.microsoft.com?

Bedeutet dies, dass Microsoft seinen eigenen Nicht-Open-Source-Dokumentationsgenerator/Engine erstellt hat, der Markdown verwendet?

Nein. Die Doc-Engine hinter https://docs.microsoft.com ist DocFX und basiert auf .NET und ist vollständig Open Source. Es verwendet Markdown für sein Format.

Hallo

Ich bin vielleicht ein bisschen spät dran, dies zu posten.

Ich frage mich nur, ob es eine API, ein Framework oder ein Tool gibt, mit dem wir eine Dokumentationssite wie die für https://docs.microsoft.com erstellen können. Mir persönlich gefällt, wie die Microsoft-Dokumentation präsentiert wird, @danroth27 erwähnte DocFX, die verwendete Engine. Ich möchte nur wissen, ob die Site selbst etwas ist, das von Grund auf neu erstellt wird, oder ob es eine Vorlage oder ein Paket gibt, das wir verwenden können verwenden, um dasselbe Erscheinungsbild zu erzeugen? nicht genau das gleiche, aber etwas, das wir ändern können :)

Danke!
Jude Alquiza.

Je mehr ich über DocFx lese , desto mehr gefällt es mir - werde es bald ausprobieren.

Wie können wir unsere eigene Dokumentationswebsite wie https://docs.microsoft.com/ intern erstellen, ohne das Rad neu zu erfinden? Wir verwenden ein gehostetes readthedocs für Python-Dokumente und ein gehostetes doxygen für c/c++-Dokumente.

Was ist der beste Weg, um alle API-Dokumente unter einem Dach zu bekommen? Wenn Sie diesen Thread lesen, scheinen viele Leute sphinx/readthedocs zu verwenden, aber wie konvertieren Sie Ihre .XML-Dokumentation in das richtige Format für diese Tools?