Klassendokumentationsvorschläge

Question

Wir sind ein Microsoft -Shop, der sich auf die Verwendung von C#konzentriert. Wir haben mehrere Projekte, einschließlich Websites, Windows -Dienste und Klassenbibliotheken, die XML -Kommentare enthalten.

Ich möchte für jedes Projekt eine HTML-Dokumentation im MSDN-Stil generieren und an einem zentralisierten Ort bereitet, auf den alle Entwickler problemlos zugreifen können. Ich möchte diese Schritte auch automatisieren, damit sie in regelmäßigen Abständen ausgeführt werden können, damit ich und die anderen Entwickler sich keine Sorgen machen müssen, wenn ich mich daran erinnere, wenn eine Änderung vorgenommen wird. Ich habe Sandcastle und Doxygen angesehen und beide scheinen gute Optionen für die Erstellung der Dokumentation zu sein, die ich möchte, aber ich brauche Ratschläge auf eine gute Möglichkeit, die Generation zu automatisieren, wie in einem nächtlichen Job oder so.

Hat jemand da draußen so etwas getan? Ich bin nicht zum Endergebnis verkauft, das HTML ist. Vor allem, wenn es eine bessere Idee gibt.

BEARBEITEN:

Ich schätze all die guten Ideen. Es gibt jetzt ein paar Routen, die ich untersuchen kann, aber ich werde nicht wissen, welche am besten funktionieren wird, bis ich die Hände schmutzig bin. Der Sandcastle Help File Builder scheint mir die besten Optionen für das zu bieten, was ich tun möchte. Deshalb werde ich diesen Vorschlag nicken. Wenn ich jedoch mehr Zeit hätte, um an der XSLT- und CSS -Lösung zu arbeiten, um die XML -Daten genau richtig aussehen zu lassen, würde ich diesen Vorschlag zuerst verfolgen.

Nochmals vielen Dank!

Answer 1

Sich ansehen Sandcastle Help File Builder. Dies verwendet eigenständige Projekte, sodass Sie sie so oft erstellen können, wie Sie möchten (zum Beispiel Nacht oder als Teil Ihres kontinuierliche Integration System jedes Mal, wenn eine Änderung eingecheckt wird).

Answer 2

Sie benötigen keine Tools von Drittanbietern, um eine schöne Dokumentation zu generieren: C# Compiler kann die Dokumentation von XML-Comments in XML ausgeben. Wenn Sie nicht zufrieden sind, können Sie auch Ihre eigene XSLT-Transoformation erzeugen, bevor Sie CSS anwenden. wie hier beschrieben (Suchen Sie nach einem Beispiel für CSS in Kommentaren!).

Alternativ können Sie diese XML -Dokumentation übernehmen und sie mit so etwas verbessern Ndoc. Hier ist ein Schöner Artikel darüber, wie es geht, leider etwas veraltet.

Sie können nur die Dokumentation Ihres Projekts manuell in eine einzelne XML -Datei erstellen, indem Sie den Compiler mit ausgeführt haben /doc:documentationfilename.xml Parameter.

Sie können auch in Visual Studio (Projekteigenschaften -> Dokumentation) angeben, um diese Option zu jedem Erstellen Ihres Projekts hinzuzufügen, damit die XML -Datei jedes Mal generiert wird, wenn Sie Ihr Projekt erstellen. Sie können dann nach dem Bau von Ereignissen anhängen, um die XML-Datei in Ihr Repository zu kopieren.

Sie können Ihren MS -Build auch auf Ihrem Team Foundation -Server einrichten, um Ihre Dokumentation zu erstellen und sie auf ähnliche Weise in das Repository zu kopieren ((/p:DocumentationFile=fileName.xml);

Answer 3

Ich mache das mit unseren Projekten. Grundsätzlich verwenden wir DoxyWizard, um die Konfiguration DoxyFile einzurichten, die die Spezifikationen für das generierte HTML festlegt. In einem Build -Server -Schritt rufe ich dann "Doxygen DoxyFile" auf.

Unsere DoxyFile ist so konfiguriert, dass sie die Doxygen -Dateien in einem von unserem Webserver sichtbaren Bereich generieren. Jeder Verpflichtung zum Kofferraum führt dazu, dass die Dokumentation automatisch umgebaut wird.