Wenn Sie mit Grunt vertraut sind, können Sie leicht .html docs mit grunt-jsdoc erzeugen.
- Dokumentieren Sie Ihren Code mit JSDoc.
- Verwenden Sie grunt-jsdoc, die intern jsdoc verwendet, um Codedokumentation zu generieren.
- Dies wird auch den Quellcode in HTML ausgeben und in der Dokumentation wird es Links zu Codezeilen für jedes öffentlich zugängliche Mitglied enthalten.
- Sie können auch Kontrolle über die Links, indem Sie einfach die
@link Direktive von JSDoc:
See {@link https://github.com/onury|My GitHub Profile}.
Siehe ein Gruntfile-Beispiel unten.
Beachten Sie, dass dies alle JSDoc CLI options unterstützt.
grunt.initConfig({
'jsdoc': {
dist: {
src: ['./src/core/mylib.js'],
options: {
destination: './doc/html'
}
}
}
});
Und Sie führen diese Aufgabe mit grunt jsdoc. Oder Sie können das Plugin grunt-contrib-watch hinzufügen, um jedes Mal, wenn sich die Datei ändert, automatisch auszuführen.
Vorlagen und Styling:
- Sie können jederzeit mit der CSS-Datei spielen und es für Ihren eigenen Geschmack zu überschreiben.
- Oder Sie können docstrap Vorlage für JSDoc3 basierend auf Bootstrap verwenden, die mit
grunt-jsdoc verwendet werden können.
Mit Jekyll für die Dokumentation:
Obwohl es nativ unterstützt wird, müssen Sie nicht Jekyll für GitHub Pages verwenden. Jekyll ist eigentlich für statische Webseiten oder Blogs gedacht. Aber es kann Markdown-Dateien nehmen.Also, ich würde zuerst github aromatisierte Markdown-Dateien aus dem Code über jsdoc-to-markdown erstellen (es gibt auch ein Grunt-Plugin grunt-jsdoc2md) dann configure ein Jekyll-Projekt entsprechend.
Beachten Sie jedoch, dass Sie Jekyll installieren und konfigurieren müssen. Hier ist eine gute article und eine sample project um mit zu beginnen.
UPDATE:
Danach beantworten, begann ich an einem Werkzeug arbeiten leicht für die Gebäudedokumentation. Jetzt ist es reif genug, hier zu posten und zu sehen, ob es dir gefällt. Es heißt Docma.
Key Docma Funktionen sind; Es kann beide JSDoc und Markdown Dateien in HTML-Dokumentation analysieren, generiert eine Web-App, extrem konfigurierbar und funktioniert hervorragend mit Github Pages.
Siehe Docma documentation here, die auch mit Docma erstellt und auf GitHub Pages gehostet wird.
Ein Beispiel-Screenshot von Docma erzeugt SPA:
i ein wenig herum sah, und ich denke, die Ausgabe html Schaben vorwärts der einfachste Weg ist. – dandavis
Ich entschied mich schließlich für die Verwendung von JSDox, die sehr sauberen Abschlag erzeugt, kombiniert mit https://github.com/shinnn/gulp-gh-pages. Sie können sehen, wie ich es hier implementiert https://github.com/edx/edx-ui-toolkit/pull/60, und das Endergebnis hier: http://ui-toolkit.edx.org. Danke für alle Vorschläge. –