Willkommen auf myCSharp.de! Anmelden | kostenlos registrieren
 | Suche | FAQ

Hauptmenü
myCSharp.de
» Startseite
» Forum
» Suche
» Regeln
» Wie poste ich richtig?

Mitglieder
» Liste / Suche
» Wer ist online?

Ressourcen
» FAQ
» Artikel
» C#-Snippets
» Jobbörse
» Microsoft Docs

Team
» Kontakt
» Cookies
» Spenden
» Datenschutz
» Impressum

  • »
  • Community
  • |
  • Diskussionsforum
sharpDox - Ein Dokumentationstool für C# | Version 1.2
nikeee
myCSharp.de - Member



Dabei seit:
Beiträge: 9

beantworten | zitieren | melden

Zitat von Abt
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?
private Nachricht | Beiträge des Benutzers
Abt
myCSharp.de - Team

Avatar #avatar-4119.png


Dabei seit:
Beiträge: 15618
Herkunft: BW

beantworten | zitieren | melden

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.
private Nachricht | Beiträge des Benutzers
C4RL0
myCSharp.de - Member

Avatar #avatar-3444.png


Dabei seit:
Beiträge: 82
Herkunft: Osnabrück

beantworten | zitieren | melden

Ich erhalte folgende Fehlermeldung, obwohl der Pfad angegeben wurde und der THML Workshop installiert ist:
Fehler
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)
Dieser Beitrag wurde 4 mal editiert, zum letzten Mal von C4RL0 am .
_____________________
Gruß
Carlo

"Palabras que no coinciden con hechos no valen nada."
private Nachricht | Beiträge des Benutzers
Geaz
myCSharp.de - Member

Avatar #avatar-3446.png


Dabei seit:
Beiträge: 150
Herkunft: Frankfurt

Themenstarter:

beantworten | zitieren | melden

@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
private Nachricht | Beiträge des Benutzers
Abt
myCSharp.de - Team

Avatar #avatar-4119.png


Dabei seit:
Beiträge: 15618
Herkunft: BW

beantworten | zitieren | melden

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...
private Nachricht | Beiträge des Benutzers
Geaz
myCSharp.de - Member

Avatar #avatar-3446.png


Dabei seit:
Beiträge: 150
Herkunft: Frankfurt

Themenstarter:

beantworten | zitieren | melden

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
private Nachricht | Beiträge des Benutzers
C4RL0
myCSharp.de - Member

Avatar #avatar-3444.png


Dabei seit:
Beiträge: 82
Herkunft: Osnabrück

beantworten | zitieren | melden

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."
private Nachricht | Beiträge des Benutzers
Abt
myCSharp.de - Team

Avatar #avatar-4119.png


Dabei seit:
Beiträge: 15618
Herkunft: BW

beantworten | zitieren | melden

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?!
private Nachricht | Beiträge des Benutzers
wcseller
myCSharp.de - Member



Dabei seit:
Beiträge: 191

beantworten | zitieren | melden

Zitat von Abt
@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)!
private Nachricht | Beiträge des Benutzers
m_d
myCSharp.de - Member



Dabei seit:
Beiträge: 2
Herkunft: Magdeburg

beantworten | zitieren | melden

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.
Fehler
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

Dieser Beitrag wurde 6 mal editiert, zum letzten Mal von m_d am .
private Nachricht | Beiträge des Benutzers
Palladin007
myCSharp.de - Member

Avatar #avatar-4140.png


Dabei seit:
Beiträge: 1429
Herkunft: Düsseldorf

beantworten | zitieren | melden

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.
private Nachricht | Beiträge des Benutzers
Abt
myCSharp.de - Team

Avatar #avatar-4119.png


Dabei seit:
Beiträge: 15618
Herkunft: BW

beantworten | zitieren | melden

Gaez hat ja bereits auf https://github.com/dotnet/docfx verwiesen.
private Nachricht | Beiträge des Benutzers
Palladin007
myCSharp.de - Member

Avatar #avatar-4140.png


Dabei seit:
Beiträge: 1429
Herkunft: Düsseldorf

beantworten | zitieren | melden

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 ^^
private Nachricht | Beiträge des Benutzers