Generieren Sie HTML-Dokumentation automatisch während eines Build mit Sandcastle

https://stackoverflow.com/questions/211693

03-07-2019
|

Frage

Welche Schritte muss ich ergreifen müssen, um HTML-Dokumentation automatisch über den Build-Schritt in Visual Studio Gebäude zu bekommen? Ich habe alle Kommentare vorhanden und die comments.xml Datei erzeugt werden, und Sandburg installiert. Ich muß nur wissen, was auf den Post-Build-Schritt hinzuzufügen, um die Dokumentation zu erzeugen.

Lösung

Einige Änderungen vorgenommen wurden, da diese Frage gestellt wurde. Sandburg nicht mehr enthält SandcastleBuilderConsole.exe. Stattdessen verwendet es nur alten MSBuild.exe.

das mit Visual Studio hier zu integrieren ist, was ich getan habe:

Dieses in Ihrem Postbuildereignis:

IF "$(ConfigurationName)"=="Release" Goto Exit

"$(SystemRoot)\microsoft.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj"

:Exit

Das wird Visual Studio führt, dass Ihre Dokumentation zu bauen, nur, wenn Sie in „Release“ Modus bauen. Auf diese Weise sind Sie nicht ewig warten, wenn Sie in „Debug“ -Modus während der Entwicklung aufzubauen.

Ein paar Anmerkungen:

Mein System ist 64-bit, wenn Sie nicht danach framework64 mit framework in dem Pfad ersetzen werden msbuild.exe.
So wie ich das Setup ist jedes Projekt in meiner Lösung individuell zu dokumentieren. Wenn Sie eine „Sandcastle Help File Builder“ Projektdatei haben, die gemeinsam mehrere Projekte enthält, dann möchten Sie wahrscheinlich loswerden ProjectName\ bekommen und doc in die Lösung Verzeichnis. In diesem Fall sollten Sie nur die Post-Build-Ereignis setzen auf das Projekt-Befehle, die in Ihrer Lösung LAST gebaut wird. Wenn Sie es in dem Post-Build-Ereignisse für jedes Projekt setzen dann werden Sie Ihre Dokumentation für jedes Projekt des Wiederaufbau, die gebaut wird. Unnötig zu sagen, würden sitzen Sie eine Weile. Persönlich bevorzuge ich individuell für jedes Projekt zu dokumentieren, aber das ist nur meine Meinung.

Installieren von Sandcastle und "Sandcastle Help File Builder".

Wenn Sie nicht wissen, wie Sandcastle und „Sandcastle Help File Builder“ Setup richtig zu bekommen, dann gehen Sie folgendermaßen vor:

Herunterladen und Installieren von Sandcastle von http://sandcastle.codeplex.com/ (wenn Sie haben ein 64-Bit-System, müssen Sie eine Umgebungsvariable hinzuzufügen. Die Anweisungen sind hier .
Download und "Sandcastle Help File Builder" installieren von http://shfb.codeplex.com/ (ignorieren Warnungen über MSHelp2, wenn Sie kommen. Sie werden mehr brauchen sie nicht.)
Wenn Sie dann diejenigen installiert verwenden „Sandcastle Help Builder Datei“ eine neue Dokumentation Projekt zu erstellen. Wenn Sie gefragt, wo die Datei gespeichert werden, ist es in der Dokumentation Ordner speichern Sie in Ihrer Lösung / Projekt. http://www.chevtek.com/Temp/NewProject.jpg
Nach dem Erstellen eines neuen Projekts müssen Sie entscheiden, welche Art von Dokumentation, die Sie erstellen möchten. Eine kompilierte Windows-Hilfe-Datei, eine Webseite oder beides. http://www.chevtek.com/Temp/DocumentationType.jpg
Wenn Sie die SHFB Projektdatei in dem Verzeichnis gespeichert, in dem Sie Ihre Dokumentation erzeugt werden sollen, dann können Sie diesen Schritt überspringen. Aber wenn Sie die generierte Dokumentation eingefügt werden sollen an anderer Stelle, dann müssen Sie den Ausgabepfad einzustellen. http://www.chevtek.com/Temp/OutputPath.jpg HINWEIS: Eine Sache im Auge über den Ausgabepfad zu halten (was mich für eine Stunde frustriert) ist, dass, wenn Sie Website als die Art der Dokumentation überprüft haben Sie wollen, es Inhalt in seinem Ausgangspfad überschreibt. Was sie vernachlässigen, Ihnen zu sagen ist, dass SHFB absichtlich bestimmte Ordner eingeschränkt von als Teil des Ausgabepfad enthalten sind. Desktop ist ein solcher Ordner. Ihr Ausgangspfad kann nicht auf dem Desktop sein, nicht einmal einen Unterordner von Desktop. Es kann nicht von Eigene Dateien entweder, aber es kann ein Unterordner meiner Dokumente sein. Wenn Sie Fehler erhalten, wenn Sie in der Dokumentation erstellen, versuchen, den Ausgabepfad zu ändern und sehen, ob es das behebt. Siehe http://shfb.codeplex.com/discussions/226668?ProjectName=shfb für Details zu diesem Thema.
Schließlich müssen Sie einen Verweis auf das Projekt, das Sie dokumentieren wollen hinzuzufügen. Wenn Sie einzelne Projekte tun, wie ich es tue, dann für jede SHFB Projektdatei, die Sie erstellen, müssen Sie die entsprechenden CSPROJ-Datei verweisen. Wenn Sie ein SHFB Projekt für die gesamte Lösung haben, dann würden Sie die SLN-Datei für Ihre Lösung finden. (Sandburg funktioniert auch, wenn Sie die kompilierten DLLs verweisen, aber da Sie es mit Visual Studio sind die Integration finde ich es sinnvoller ist, das Projekt zu referenzieren / Lösung statt Dateien. Dies kann bedeuten auch, dass es wirklich keine Rolle, die Sie projizieren tun, um das Post-Build-Ereignis auf, da es den Code anstelle des DLLs verweisen, aber es ist besser, sicher und auf dem letzte Projekt legt es zu sein, das ist gebaut) http://www.chevtek.com/Temp/AddSource.jpg
Speichern Sie das Projekt und Sie können "Sandcastle Help File Builder" schließen. Jetzt ist alles Setup. Nur sicher sein, die Dokumentation Projektdatei in den entsprechenden Ordnern zu setzen, die die Batch-Befehle zu Punkt in dem Post-Build-Ereignisse.

Ich hoffe, mein kurzes Tutorial hilft Ihnen heraus! Es war sehr schwer für mich, jeden anständig Tutorials zu finden mich zeigen, wie Sandburg zu verwenden, geschweige denn, wie es mit Visual Studio zu integrieren. Hoffentlich Zukunft Google-Suchen werden diese Frage auftauchen.

Andere Tipps

Ich empfehle Ihnen, Sandcastle Help Builder Installationsdatei von Codeplex .

Sie können dies über die Befehlszeile ausführen, z von einem Post-Build-Ereignisse. Die einfachste Befehlszeile lautet:

<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb

Sandcastle ist sehr langsam, so dass ich laufen sie nur für Release-Builds. Um dies zu tun, erstellen Sie ein Ereignis Postbuild mit einem Befehl so etwas wie die folgenden, die die Konfigurationsnamen in eine Batch-Datei übergibt:

CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)

Dann in der Batch-Datei können Sie testen, ob das erste Argument „Release“ und wenn ja läuft SandcastleBuilderConsole.exe.

Eine einfache Möglichkeit, dies zu tun, wie oben vorgeschlagen wird mit Sandcastle Help Builder Datei. Es wurden einige Änderungen an den Build-Prozess aus dem Zeilenbefehl gemacht und jetzt können diese Projekte mit MSbuild statt SandcastleBuilderConsole.exe gebaut werden. Also alles, was Sie tun müssen, ist:

MSBuild.exe ProjectName.shfb

Ich muss zugeben, dass ich die aktuelle Version von Sandcastle etwas zu wünschen übrig finden; für große Projekte ist es ziemlich langsam, und es ist nicht leicht zu integrieren (da es noch zu früh ist).

Für die regelmäßigen Gebrauch, ich habe es tatsächlich einfacher findet nur Reflektor in einem Ordner mit den DLL-und XML-Dateien zu verweisen -. IIRC, wird die XML-Datei laden (s), wie Sie um navigieren

Plus ich fast immer Reflektor haben öffnen sowieso ...

[Bearbeiten] geprüft, und ja - xml Kommentare zeigen im Disassembler Panel

Installieren Sie diese:

NDoc: http://prdownloads.sourceforge.net/ndoc /NDoc-v1.3.1.msi?download

HTML Help Workshop: http : //www.microsoft.com/downloads/details.aspx FamilyID = 00535334-c8a6-452f-9aa0-d597d16580cc & displaylang = en

Verwenden Sie dann die NDocConsole.exe Befehlszeile Dokumentation entweder in MSDN oder CHM Form zu erzeugen:

@c: \ progra ~ 1 \ NDoc \ NDocConsole.exe MyCode.dll, MyCode.xml -Documenter = MSDN-CHM

Ich selbst habe ein externes Tool dafür gemacht und gab es eine Verknüpfung, aber wie das vorher bereits erwähnt können Sie es zu einem postbuild Ereignis anschließen und los geht.

(PS Ich habe oben ein paar Jahren das Setup wurde jetzt mit und bin sehr glücklich mit ihm)

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow