Laden...

sharpDox - Ein Dokumentationstool für C# | Version 1.2

Erstellt von Geaz vor 11 Jahren Letzter Beitrag vor 4 Jahren 131.839 Views
2.078 Beiträge seit 2012
vor 7 Jahren

Hi Geaz,

ich hab bei deinem letzten Stand eine Exception, wenn ich zu unserem Projekt eine Doku erstellen möchte.
Die sharpDox-Version habe ich vor ein paar Minuten erst herunter geladen.

Die Die Meldung:

Fehlermeldung:
System.IO.FileNotFoundException: Die Datei oder Assembly "System.Threading.Tasks.Dataflow, Version=4.5.24.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" oder eine Abhängigkeit davon wurde nicht gefunden. Das System kann die angegebene Datei nicht finden.

Die vollständige Exception-Meldung liegt nochmal im Anhang.

Eventuell noch von Bedeutung:
Das Projekt ist größtenteils in VB.NET geschrieben.
Es wird aktuell mit Visual Studio 2013 entwickelt

Kannst Du dir das mal anschauen?

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 7 Jahren

Hallo Palladin,

bisher wurde sharpDox nur mit C# .NET Programmen getestet.
Da sharpDox inzwischen auf Roslyn aufbaut sollte VB.NET kein großes Problem mehr darstellen, aber wurde bisher noch nicht getestet. Deshalb kann es dort durchaus zu Fehlern kommen.

Werde mir dies für das nächste Release vornehmen.

16.807 Beiträge seit 2008
vor 7 Jahren

Planst Du irgendwas in Richtung .NET Core und irgendeiner Art .NET Core CLI, sodass man das ganze sehr einfach in Continuous Integration einbetten könnte?

Dann könnte man das ganze Ding auch innerhalb eines Docker Containers laufen lassen.

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 7 Jahren

Bisher plane ich da noch nichts. Werde es mir aber mal anschauen. Denke nicht, dass das zu aufwendig wird.

Momentan sitze ich an einer Visual Studio Extension, um sharpDox direkt aus einem Projekt heraus starten zu können. Ohne ein extra Tool für die Dokumentation öffnen zu müssen.

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 7 Jahren

@Abt: Was fehlt dir denn an der aktuellen Konsolenanwendung? Die sollte doch auch bereits in einem CI System integrierbar sein. Oder ging es dir explizit, um eine Konsolenanwendung die unter .NET Code läuft?

16.807 Beiträge seit 2008
vor 7 Jahren

.. jetzt weiß ich, warum Du auf .NET Core migrieren wolltest: ich hatte Dich ja danach gefragt. 8o

Ging mir eher auf .NET Core, damit ich das Projekt als eigenständige Runtime in einem Docker Container (Linux) laufen lassen könnte.
Quasi Code Documentation as a Service. Dann müssen sich die ganzen Devs das nicht installieren, sondern wir haben was zentrales, was alle nutzen können.

2.078 Beiträge seit 2012
vor 7 Jahren

Ein weiterer Gedanke:

Kannst Du einbauen, dass bei Bedarf auch der Quellcode jeder Methode, Property, etc. eingefügt wird?
Wenn ich dann beispielsweise eine Property-Definition habe, dass ich dann durch einen Mausklick den Body der Property ausklappen kann. Ähnlich wie es auch Visual Studio macht.

Auf diese Weise könnte man sich mit Hilfe der Dokumentation durch den vollständigen Code lesen, was besonders für jemanden, der neu bei einem Projekt ist, hilfreich sein kann.

Super wäre auch eine entsprechende Unterstützung von Typ- und Member-Links im Code selber, wie es auf der Reference Source-Seite von Microsoft gemacht ist.
Ich persönlich finde diese Möglichkeit, die Microsoft da bietet, klasse und mit deinem SharpDox könnte ich das dann für jedes C# und (hoffentlich bald) VB.NET Projekt haben ^^

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 7 Jahren

An .NET Core werde ich dran bleiben, da ich die von dir genannte Lösung interessant finde. Zudem fände ich es einfach super wenn sharpDox unter Linux laufen würde.

@Palladin007:

Ich habe mal etwas angefangen (siehe Anhang). Ich habe es nun so eingebaut, dass bei (1) zwischen der Doku und dem Code gewechselt werden kann. Zudem siehst du bei (2), dass Hervorhebungen der Zeilen möglich sind. Die Idee ist, dass direkt aus der Doku von einem Member aus zu der entsprechenden Stelle im Code gesprungen werden kann. Diese wird dann auch hervorgehoben wie bei (2). Das Ganze ist dann auch verlinkbar.

Zudem möchte ich, dass der Dateinamen ein direkter Link zu z.B. Github ist, falls eine SCM Base Url angegeben wurde.

2.078 Beiträge seit 2012
vor 7 Jahren

Sieht gut aus ^^
Die Idee, den Member, über den man zum Code gekommen ist, gefällt mir, würde ich mir bei dem .NET-Code von Microsoft auch wünschen 😄

Wenn man jetzt noch im Code auf Typen, Member, etc. klicken kann und dann zur entsprechenden Stelle in der Doku kommt, dann ist's perfekt ^^

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 7 Jahren

Habe mal eine neue Version veröffentlicht. Mit dabei ist das neue Code Tab, falls im HTML Exporter 'Show Code' aktiviert wurde.

Verlinken von Typen etc. im Code habe ich dann für die nächste Version auf der Agenda 😃

Grüße
Geaz

N
9 Beiträge seit 2012
vor 7 Jahren

Quasi Code Documentation as a Service. Dann müssen sich die ganzen Devs das nicht installieren, sondern wir haben was zentrales, was alle nutzen können.

Da wäre es wirklich super, wenn man eine statische HTML-Seite emittiert, damit man das direkt auf Github-Pages pushen kann, wenn der CI-Build durchläuft.
Sollte ja jetzt auch schon gehen, oder? Wie würde man das am besten machen?

16.807 Beiträge seit 2008
vor 7 Jahren

Naja, das was sharpDox erzeugt, ist ja statischer Code. Alles dynamische ist nur JavaScript.
Du kannst es also problemlos auf den GitHub Pages hosten. Mach ich auch: https://quickio.net/Docs/v2.0.1.0/

Was ich derzeit versuche:

  • sharpDox echte Kommandozeilenfähigkeit zu vermitteln (Mein Fork: https://github.com/BenjaminAbt/sharpDox)
  • sharpDox dann als Teil des Continuous Integration Prozesses zu integrieren (neue Stable Version = neue Doku)
  • verschiedene Versionen auf github Pages zur Verfügung zu stellen.

letztes seh ich aktuell noch als Problem an. Warum:
Ich will auf der GitHub Page quasi für jede Version der Doku einen Unterordner (=> https://github.com/SchwabenCode/QuickIO.Web/tree/master/help).
Das würde bedeuten, dass ich im CI Prozess erst nen git fetch machen müsste, die neue Version hinzufügen und dann einen git push.
Das kostet aber Zeit, was gerade dann bei kleinen Bibliotheken, deren Builddauer nur wenige Sekunden dauert, dann unverhältnismäßig erscheinen lässt.
Zudem natürlich die Builddauer, wenn man zB. VSTS in der Cloud für private / Kundenprojekte hat und damit Kosten erzeugt.
Da hab ich auch noch keine Lösung, wie ich letzteres am geschicktesten machen könnte.

Wenn das mit GitHub nicht wie gedacht funktioniert, dann wäre meine ALternative, dass ich nen Cool Blob Storage auf Azure erstelle und dort nur die Hilfedateien hochlade.
DIe geringste Einheit von Cool Blob Storage wäre 1 GB, was ~ 0,01€ pro Monat kosten würde.
Dort kann ich aber via FTP hochladen, das was Unterordner-Thema einfacher machen würde.

Wenn da jemand Ideen hat: gerne anschreiben oder mich auf Twitter anpingen.

96 Beiträge seit 2012
vor 7 Jahren

Ich erhalte folgende Fehlermeldung, obwohl der Pfad angegeben wurde und der THML Workshop installiert ist:

Fehlermeldung:
Could not find the chm compiler. Please set the correct path in the chm settings.
Die Dokumentation konnte nicht erstellt werden.
SharpDox.Build.SDBuildException: Es gab ein Problem mit den Vorraussetzungen eines oder mehrere Exportern. Siehe Bauausgabe für weitere Informationen.
bei SharpDox.Build.Context.Step.ExtendedCheckConfigStep.RunStep(SDProject sdProject)


Gruß
Carlo

"Palabras que no coinciden con hechos no valen nada."

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 7 Jahren

@C4RL0: Entschuldige die sehr späte Antwort. Hast du das Problem inzwischen gelöst?

Hallo an alle!

Langsam aber sicher macht sich das .net Core Framework breit und ich liebäugle immer mehr mit einer Portierung von sharpDox. Nun habe ich mir viele Gedanken gemacht und würde diese Gelegenheit gerne nicht nur dazu nutzen eine einfache Portierung zu erstellen. sharpDox ist nun schon einige Jahre alt und ist seitdem immer mehr gewachsen. Anfangs war es ein "Proof of Concept" und ist bis heute zu einem recht nützlichem Tool herangewachsen.

Für das neue Framework würde ich sharpDox gerne einem kompletten Refactoring unterziehen und dabei vorallem auf eine gute Dokumentation wert legen. Dadurch erhoffe ich mir mehr Pull Requests in der Zukunft. Gute Dokumentation = Mehr Entwickler verstehen den Code und beteiligen sich an dem Projekt.

Zudem habe ich mir überlegt, ob es nicht sinnvoll wäre sharpDox nicht um Codeprojekte "kreisen" zu lassen. Sondern stattdessen sharpDox vor allem zu einem Dokumentengenerator zu machen. sharpDox soll in erster Linie jegliche Art von Dokument (PDF, Html, epub etc.) aus einer Sammlung von Markdowns erstellen können (ähnlich z.B. Gitbook).

Dazu würde sharpDox dann wieder pluginfähig sein. Diese Plugins könnten dann eigene Direktiven erstellen, die in den Markdowns verwendet werden können. Eine Direktive würde dann z.B. eine C# Lösung einlesen und eine Code Dokumentation in das Endprodukt inkludieren.

Was haltet ihr davon? Was sind eure Schmerzpunkte, die ihr gerne in einer neuen Version gelöst sehen würdet?

Danke und Grüße
Geaz

16.807 Beiträge seit 2008
vor 7 Jahren

Kurz wegen dem Naming:
Es heisst .NET Core und nicht .NET Core Framework. Es ist kein Framework, wie die alte .NET Framework Welt!
Da sollte man aufpassen, da ansonsten A das versteht und B das.

Markdown-Engines oder Markdown-Generatoren gibt es mittlerweile wie Sand am Meer. Der verbreitetste hier ist Jekyll, auf das auch GitHub und die Microsoft Dokumentation setzt.
Hier versuchen Konkurrenz zu machen: da musste schon was extrem gutes haben.

Ich fände es persönlich besser, wenn Du Deiner Linie treu bleibst und Code Dokumentation machst.
Lieber erweitere Deine Engines um F#, VB.NET...

Geaz Themenstarter:in
148 Beiträge seit 2013
vor 6 Jahren

Hallo zusammen,

je mehr ich mir docFX anschaue, desto mehr frage ich mich, ob es überhaupt noch einen Bedarf an sharpDox gibt.

DocFX macht fast alles was auch sharpDox macht und hat mit Microsoft einen großen Player hinter dem Projekt.

Ich bin momentan stark am überlegen, ob es überhaupt noch Sinn macht an sharpDox festzuhalten oder es vielleicht sinnvoller ist die Energie in DoxFX zustecken, um dort eventuell fehlende Features als Plugins/Templates umzusetzen.

Wie seht ihr das?

Beste Grüße

96 Beiträge seit 2012
vor 6 Jahren

Nachdem ich den passenden html-Workshop installiert und das Tool zum laufen bekommen habe, bin ich eigentlich zufrieden mit sharpDox.

Ich fänd es schade, wenn Du das Projekt einstellen würdest. docFX habe ich mir nicht angeschaut. Ich mag Tools, die Intuitiv zu bedienen sind, zumindest was ein erstes schnelles Ergebnis betrifft. Trifft das auf docFX zu? Die Doku lässt auf gegenteiliges schließen, das kann aber auch an mir liegen. 😉

Von meiner Seite aus nochmal großes Lob an Dein Projekt


Gruß
Carlo

"Palabras que no coinciden con hechos no valen nada."

16.807 Beiträge seit 2008
vor 6 Jahren

Ich muss zugeben, dass ich mittlerweile auch docFX nutze und echt begeistert bin!
Vor allem die sehr einfache Integration in Continuous Integration ist echt super. Aufwand = 0.

@C4RLO, ob die UX für Dich passt: probiers doch einfach mal aus?!

W
195 Beiträge seit 2008
vor 6 Jahren

@C4RLO, ob die UX für Dich passt: probiers doch einfach mal aus?!

Ehrlich gesagt kann ich sowas wie ein UI - abgesehen von der Commandozeile nicht finden. Kann sein, dass das Ergebnis besser/vergleichbar ist als/mit SharpDox und das sich das Ganze besser in VS integrieren lässt, aber da ich SharpDox nicht täglich brauche ziehe ich dessen verständliche UI DEUTLICH diesem docFX vor. Mit dem Ergebnis von SharpDox kann ich für meinen Bedarf sehr sehr gut leben und eine tiefere Integration in VS brauche ich nicht unbedingt...

Also ja, ich würde es begrüßen, wenn SharpDox am Leben erhalten wird... Viele Dank an Gaez, für dieses wirklich sehr hilfreiche udn nützliche Tool (kann man gar nicht oft genug sagen)!

M
2 Beiträge seit 2017
vor 6 Jahren

Hallo zusammen,

bei mir erscheint beim "Bauen" (Version 1.2.2) eine FileNotFoundException:

Starte Schritt: "Lese Projektdatei"
Starte Schritt: "Lese Code"
Starte Schritt: "Exportiere Dokumentation"

Die Dokumentation konnte nicht erstellt werden.

Fehlermeldung:
System.IO.FileNotFoundException: SharpDox.Sdk.SDPath
bei System.Drawing.Image.FromFile(String filename, Boolean useEmbeddedColorManagement)
bei SharpDox.Plugins.Html.Steps.CopyThemeStep.CopyFavIcon()
bei SharpDox.Plugins.Html.Steps.CopyThemeStep.RunStep()
bei SharpDox.Plugins.Html.HtmlExporter.Export(SDProject sdProject, String outputPath)
bei SharpDox.Build.Context.Step.ExportStep.RunAllExporters(SDProject sdProject)
bei SharpDox.Build.Context.Step.ExportStep.RunStep(SDProject sdProject)
bei SharpDox.Build.Context.BuildContext.StartBuild()

//EDIT: Problem tritt nur auf, wenn ein Favicon ausgewählt wird
nachdem ein Favicon über den Browser ausgewählt worden ist, wird der Pfad in der Textbox nicht aktualisiert, es steht weiterhin "optional" drin

**

2.078 Beiträge seit 2012
vor 4 Jahren

Wird das Projekt noch gepflegt?

Ich hab das Problem, dass beim HTML-Exporter nichts generiert wird bzw. ich nur den Website-Rumpf ohne Inhalte habe. Das kriege ich auch mit einem Dummy-Konsolen-Projekt reproduziert.
Bei einer produktiven Solution ist es so, dass einige Projekte aus der Mappe angezeigt werden, Andere nicht, wenn ich eines dieser Projekte direkt auswähle, dann ist die Doku wieder leer. Ich erkenne keinen Unterschied und bei einer anderen Solution ist wieder gar nichts zu sehen.

Wir verwenden produktiv VS2019, .NET 4.61, C# 7.3
Besagtes Dummy-Konsolen-Projekt hab ich testweise mit VS2017, .NET 4.0 und C# 6.0 aufgebaut.

Wäre schade, wenn das hier langsam stirbt, mein Vorgesetzter war begeistert, als ich ihm die halbe Doku von einem unserer produktiven Projekte gezeigt habe, dass wir die andere Hälfte nicht gefunden habe, hat die Begeisterung natürlich etwas gehemmt.

16.807 Beiträge seit 2008
vor 4 Jahren

Gaez hat ja bereits auf https://github.com/dotnet/docfx verwiesen.

2.078 Beiträge seit 2012
vor 4 Jahren

Das hatte ich nicht mehr auf dem Schirm.

Aber danke für die Info, dann weiß ich Bescheid und hab gleich eine Alternative zum Testen ^^