Eigenständige Software zum Generieren einer statischen HTML-Dokumentation aus Markdown

Ich suche nach einem Tool, das statische HTML-Seiten aus Markdown-Dateien generieren kann. So weit so gut, es gibt viele:

Mein Problem ist, dass ich eine Dokumentation für ein eigenständiges Software-Repository schreiben möchte. Es sollte wie folgt funktionieren:

  • Entwickler startet seine Workstation (Standard Windows 7)
  • Entwickler checkt Repository aus (enthält Markdown-Dateien und das zu generierende Tool)
  • Der Entwickler führt die Doc-Generierung aus, sagen wir, indem er anruftcreateDocs.bat
  • Der Entwickler öffnet die generierte index.html in seinem Browser

Mein Problem ist nun, dass alle oben genannten Tools eine Art Umgebung benötigen, die zuvor eingerichtet wurde: node.js, Python und zusätzliche Module, ... Die Idee hinter der in sich geschlossenen Umgebung ist jedoch

  • Es läuft auf Offline-Hosts
  • Es läuft auf Hosts, auf denen keine Software installiert werden kann
  • Es läuft hinter einem Unternehmens-Proxy

Kennt jemand ein gutes Tool, das so funktioniert? Gibt es Möglichkeiten, die oben genannten Tools zum Laufen zu bringen? Ich habe gerade viele Dinge ausprobiert, wie das Konvertieren von mkdocs mit py2exe, hatte aber keinen Erfolg ...

Warum ist die Ausführung auf Hosts erforderlich, auf denen keine Software installiert werden kann? Sie haben das Wort „Entwickler“ verwendet; Vermutlich hat er eine gewisse Kontrolle über seinen Computer und kann "Software installieren", Sie bestehen sogar darauf, dass er "das Repository auschecken" kann, was bedeutet, dass er (aus praktischen Gründen) Versionsverwaltungssoftware installiert haben muss.

Antworten (2)

Sauerstoff

Doxygen ist ein Allzweck-Code-Dokumentationstool. Es unterstützt Markdown ab Version 1.8.0 und kann statische HTML-Dateien neben vielen anderen Formaten generieren.

Merkmale:

  • Plattformübergreifend. Läuft auf allen Windows-Versionen seit XP
  • Hat eine portable Installation, die Sie mit Ihrem Repository bündeln könnten, damit sie offline und ohne Administratorrechte ausgeführt wird:

Ihr gewünschter Workflow lässt sich mit doxygen ganz einfach realisieren:

Bei den meisten VCSs ist es eine wirklich schlechte Idee, Binärdateien einzuchecken - es gibt viele Diskussionen im Netz darüber, warum, aber im Grunde gehört es nicht in das VCS, wenn es kein Quellcode ist.
@SteveBarnes Stimmt. In diesem Fall reicht es aus, die Konfigurations- und Batch-Dateien einzuchecken, da jeder die ausführbare Datei von der Doxygen-Website herunterladen und ausführen könnte.
Nach meinem Verständnis ist es nicht schlecht, Binärdateien per se einzuchecken. Es ist nur ein Problem, wenn Sie auch die Quellen zur Verfügung haben (dann ist es überflüssig). Im Falle von Doxygen oder anderen Drittanbietern ist dies eine gute Möglichkeit, um sicherzustellen, dass die Umgebung, mit der die Software erstellt wird, gleich bleibt.
@MONsDaR Es gibt definitiv keine Regel dagegen. Ich denke, die meisten Argumente besagen, dass es keinen Sinn macht, sie zu versionieren, da Sie keine VC-Tools (wie diff) für Binärdateien verwenden können. Aber in Ihrem Fall denke ich, dass die Bequemlichkeit, die ausführbare Datei in einem bestimmten Pfad zu haben, ein guter Grund ist, sie einzuschließen.
Einige (viele) VCS-Systeme werden sehr langsam und unhandlich, wenn sie Binärdateien gespeichert haben - mein bevorzugter Ansatz ist es, einen bekannten Ort zu haben, an dem eine oder mehrere spezifische Versionen der Eingabe-Binärdateien gespeichert sind, und ein versioniertes Skript, das die abruft erforderliche Fassung. Es ist dann immer noch ein zweistufiger Prozess - Update vom VCS dann machen, (genau so, als ob das Tool im VCS wäre). Sie können eine bestimmte Version des Tools für eine bestimmte Version Ihrer Quelle usw. anbinden. Auch in der Firma, für die ich arbeite, gibt es eine spezielle Regel dagegen.
Diese Diskussion entfernt sich etwas von der ursprünglichen Frage, sorry dafür. @Steve: Wenn Sie die Binärdateien auf einem Server speichern und ein Benutzerskript erstellen, das die richtige Version abruft - erstellen Sie nicht einfach manuell neu, wofür ein VCS entwickelt wurde? Woher wissen Sie, welche Binärdateien zu welcher Revision passen? Wie können Sie garantieren, dass eine bestimmte Revision die richtigen Binärdateien vor Ort hat? Dies sind meiner Erfahrung nach einige der größeren Probleme: 1. Die richtige Umgebung eingerichtet haben, bevor man Dinge erledigen kann. 2. Reproduzieren, was einmal mit einer bestimmten Drittanbieter-Version funktioniert hat

Ich kann mir ein paar Möglichkeiten für dich vorstellen:

Eigenständige Binärdateien

  1. Portable Python - Sie müssten wahrscheinlich einen der oben genannten Dokumentgeneratoren oder möglicherweise Sphinx auswählen und ihn zu Ihrer portablen Python-"Installation" hinzufügen.
  2. Pandoc wurde als verschiebbare Binärdatei erstellt, wie hier erklärt .

Beide oben genannten Anforderungen erfüllen:

  • Es läuft auf Offline-Hosts
  • Es läuft auf Hosts, auf denen keine Software installiert werden kann
  • Es läuft hinter einem Unternehmens-Proxy

Aber in jedem der oben genannten Fälle würde ich dringend empfehlen, Ihren gewünschten Workflow zu ändern, um einen Schritt "Entwickler lädt das Tool herunter und entpackt es" hinzuzufügen, da es viele Gründe gibt, Binärdateien nicht in Revisionskontrollsysteme zu stellen, und viele Unternehmens-VCSs haben spezifische Richtlinien um Sie daran zu hindern.

Server innerhalb der Firewall

Die andere Option könnte darin bestehen, einen Online-Dokumenterstellungsserver zu erstellen, jedoch hinter der Unternehmens-Firewall. Dies würde nicht offline funktionieren, würde aber viel mehr Kontrolle darüber bieten, welche Software verwendet wird. Dies könnte auch über Hooks in das VCS integriert werden, sodass der Workflow folgendermaßen geändert wird:

  • Der Entwickler fährt seine Workstation hoch
  • Entwickler Checkt das Repository aus – dazu müssen sie online sein
  • Der Post-Checkout-Hook sendet den Markdown an den Dokumentengenerator-Server, während sie noch online sind , der den HTML-Code auf ihrem lokalen Laufwerk generiert.
  • Der Entwickler nimmt Änderungen am Markdown vor – dies könnte offline erfolgen .
  • Der Entwickler generiert HTML aus dem modifizierten Markdown, um seine Arbeit zu überprüfen – entweder muss er online sein oder eine lokale Installation desselben Tools haben, um dies zu tun.
  • Entwickler-Commits-Änderungen müssen dazu sowieso wieder online sein

Dies erfüllt nicht Ihre erste Anforderung, bietet aber einige Vorteile:

  • Sie können fast jedes Werkzeug verwenden, das Sie benötigen
  • Es gibt keine Probleme mit Tools zur Versionskontrolle
  • Ihre Entwickler müssen nicht alle Windows ausführen
  • Ihr Dokumentgenerator kann Zugriff auf Ressourcen haben, die Sie möglicherweise nicht auf dem Entwicklercomputer installieren möchten, z. B. könnte der HTML-Code Berichte enthalten, die von Ihrem Problemverfolgungssystem oder von einem Fortschrittsberichtssystem generiert wurden.
Ich habe bereits darüber nachgedacht, einen Server einzurichten, um die Dokumentation zu generieren. Beide Methoden haben ihre eigenen Vorteile. Werde das morgen besprechen.
Eigenständige Software zum Generieren einer statischen HTML-Dokumentation aus Markdown
AntwortenHierDatenschutz-Bestimmungen1y, 1v