it-swarm.com.de

Wie kann ich eine JavaScript-API-Dokumentation für GitHub Pages erstellen?

Es gibt viele großartige Optionen zum Generieren der API-Dokumentation für andere Sprachen, aber ich muss noch eine Lösung für meine JavaScript-API finden, die ich auf GitHub-Seiten hosten möchte. Es scheint, dass ich JSDoc3 verwenden kann, aber ich würde ein benutzerdefiniertes Plugin erstellen müssen, das Jekyll-Markup ausgibt. 

Ich möchte auch, dass die Code-URLs auf GitHub selbst verlinkt werden. Ich habe jsdoc-githubify gefunden, das die Ausgabe verändert, um die Links zu ändern, aber ich würde eine einfachere Option vorziehen, bei der ich mehr Kontrolle habe.

Muss ich mein eigenes JSDoc-Plugin erstellen, oder gibt es da draußen eine bessere Lösung, die ich vermisst habe? Was benutzen die Leute dafür?

30
Andy Armstrong

Wenn Sie mit Grunt vertraut sind, können Sie mit Grunt-jsdoc problemlos .html-Dokumente erstellen. 

  • Dokumentieren Sie Ihren Code mit JSDoc .
  • Verwenden Sie grunt-jsdoc , das intern jsdoc verwendet, um Codedokumentation zu generieren.
  • Dies gibt den Quellcode auch in HTML aus und enthält in der Dokumentation Links zu Codezeilen für jedes öffentlich zugreifbare Mitglied.
  • Sie können die Links auch steuern, indem Sie einfach die @link-Direktive von JSDoc verwenden:
    See {@link https://github.com/onury|My GitHub Profile}

Unten finden Sie ein Beispiel für eine Gruntdatei.
Beachten Sie, dass dies alle JSDoc CLI-Optionen unterstützt.

grunt.initConfig({
    'jsdoc': {
        dist: {
            src: ['./src/core/mylib.js'],
            options: {
                destination: './doc/html'
            }
        }
    }
});

Und Sie führen diese Aufgabe mit grunt jsdoc aus. Oder Sie können das grunt-contrib-watch-Plugin hinzufügen, um bei jeder Änderung der Datei automatisch ausgeführt zu werden.

Vorlagen und Styling:  

  • Sie können jederzeit mit der CSS-Datei spielen und sie nach Ihrem eigenen Geschmack überschreiben.
  • Oder Sie können docstrap template für JSDoc3 verwenden, das auf Bootstrap basiert und mit grunt-jsdoc verwendet werden kann.

Verwendung von Jekyll zur Dokumentation:  

Obwohl es nativ unterstützt wird, müssen Sie Jekyll nicht für GitHub Pages verwenden. Jekyll ist eigentlich für statische Websites oder Blogs konzipiert. Es kann jedoch Markdown-Dateien dauern. Also würde ich zuerst github-markierte Markdown-Dateien aus 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 zur Installation und Konfiguration von Jekyll zusätzliche Arbeit ausführen müssen. Hier ist ein guter Artikel und ein Beispielprojekt zum Beginnen. 

UPDATE:  

Nachdem ich dies beantwortet hatte, begann ich leicht an einem Werkzeug für die Erstellung von Dokumentation zu arbeiten. Jetzt ist es reif genug, um hier zu posten und zu sehen, ob es Ihnen gefällt. Es heißt Docma

Die wichtigsten Funktionen von Docma sind: Es kann sowohl JSDoc als auch Markdown - Dateien in die HTML-Dokumentation einlesen, eine Web-App erstellen, extrem konfigurierbar und funktioniert hervorragend mit Github Pages .

Siehe Docma-Dokumentation hier , das ebenfalls mit Docma erstellt und auf GitHub-Seiten gehostet wird.

Ein Beispiel eines von Docma generierten SPAs:

enter image description here

20

Ich denke, das ist, wonach Sie suchen: http://jsdox.org/

jsdox ist ein einfacher Jsdoc 3 Generator. Es ruft Dokumentations-Tags basierend auf einer Untergruppe von Jsdoc 3 aus Ihren Javascript-Dateien ab und generiert Markdown-Dateien.

5
Xavi Magrinyà

JSDox ist genau das, was Sie suchen.

2
Charlie H

Ich bin ein Fan von Swagger: https://github.com/swagger-api/swagger-ui & http://swagger.io/

Es enthält mehr als nur API-Dokumentation, daher ist es vielleicht zu viel für Sie, aber es macht eine gute Arbeit, APIs zu dokumentieren. 

1
obi1

versuchen, es zu vereinfachen

  • In GitHub-Seiten, die API-Dokumentation generieren, die Jekyll-Markup ausgibt.

    Entkomme der Flüssigkeitsschablone mit {% raw %} Etikett.

    {% raw %}
       I want to be {{escaped}}.
    {% endraw %}
    

    ref: github/.com/Shopify/liquid/wiki/Liquid-for-Designers # raw

    ref: jekyllrb/.com/docs/github-pages/# projektseiten

    erstellen Sie zwei Zweige, einen für Master und einen für Gh-Seiten. Der Master-Zweig enthält Ihre .md-Datei und Gh-Seiten enthalten statisch erzeugte .html-Dateien. Auf dem lokalen Computer: $ jekyll build im aktuellen Projektordner wird generiert in ./_site.

    auf GitHub hochladen.

    jekyll

    • hauptzweig: github/.com/jekyll/jekyll
    • gh-pages-Zweig: github/.com/jekyll/jekyll/tree/gh-pages

    fb/reagieren

    • hauptzweig: github/.com/facebook/react/edit/master/docs/docs/ref-01-top-level-api.md
    • gh-pages branch: github/.com/facebook/reagieren/blob/gh-pages/docs/top-level-api.html
  • Seiten-URLs verweisen auf das GitHub-Dokument selbst.

    Im _layouts Ordner (HTML-Vorlage) Link hinzufügen "Edit on GitHub" auf Dokumentseiten das ist Blog-Post darüber

  • 0
    blinksmith

    Obwohl ich es seit einiger Zeit nicht aktualisiert habe, ist https://github.com/punkave/dox-foundation eine andere Option. Es werden nur HTML-Dateien generiert, die Sie an Ihren gh-pages-Zweig übergeben können. 

    0
    mattmcmanus