Come posso generare la documentazione dell'API JavaScript per GitHub Pages

Question

Ci sono molte ottime opzioni per generare documentazione API per altre lingue, ma devo ancora trovare una soluzione per la mia API JavaScript che voglio ospitare su GitHub Pages. Sembra che io possa usare JSDoc3 ma avrei bisogno di creare un plugin personalizzato che emetta il markup di Jekyll.

Vorrei anche che gli URL di codice si colleghino a GitHub stesso. Ho trovato jsdoc-githubify che muterà l'output per cambiare i collegamenti, ma preferirei una opzione più diretta in cui ho più controllo.

Devo creare il mio plugin JSDoc, o c'è una soluzione migliore là fuori che ho perso. Cosa usa la gente per questo?

Answer 1

credo che questo è quello che stai cercando: http://jsdox.org/

jsdox è un semplice generatore jsdoc 3. Estrae tag di documentazione basati su un sottoinsieme di jsdoc 3 dai file javascript e genera file di markdown.

Answer 2

Se si ha familiarità con Grunt, si può facilmente generare .html documenti con grunt-jsdoc.

• Documentare il codice con JSDoc.
• Utilizzare grunt-jsdoc che utilizza internamente jsdoc per generare la documentazione del codice.
• Questo produrrà anche il codice sorgente in HTML e all'interno della documentazione includerà collegamenti a righe di codice per ogni membro accessibile pubblicamente.
• È inoltre possibile avere il controllo sui collegamenti semplicemente utilizzando la direttiva @link di JSDoc:
  See {@link https://github.com/onury|My GitHub Profile}.

Vedere un esempio di Gruntfile di seguito.
Si noti che questo supporta tutti JSDoc CLI options.

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

e si esegue questo compito con grunt jsdoc. Oppure puoi aggiungere il plug-in grunt-contrib-watch per l'esecuzione automatica ogni volta che il file cambia.

Modelli e Styling:

• Si può sempre giocare con il file CSS e sovrascrivere per il proprio gusto.
• Oppure è possibile utilizzare il modello docstrap per JSDoc3 basato su Bootstrap che può essere utilizzato con grunt-jsdoc.

Utilizzando Jekyll per la documentazione:

Anche se è supportato nativamente, non c'è bisogno di utilizzare Jekyll per GitHub pagine. Jekyll è in realtà progettato per siti Web statici o blog. Ma può prendere i file markdown.Quindi, per prima cosa creerei i file markdown di sapore github dal codice tramite jsdoc-to-markdown (c'è anche un plugin Grunt grunt-jsdoc2md) e successivamente un progetto di Jekyll di configure.

Tuttavia, è necessario fare del lavoro extra per installare e configurare Jekyll. Ecco un buon article e un sample project per iniziare.

UPDATE:

Dopo aver risposto a questo, ho iniziato a lavorare su uno strumento per la creazione di documenti con facilità. Ora, è abbastanza maturo da postare qui e vedere se ti piace. Si chiama Docma.

Le funzioni chiave di Docma sono; può sia analizzare i file JSDoc e Markdown nella documentazione HTML, generare una web-app, estremamente configurabile e funziona perfettamente con Github Pages.

Vedere Docma documentation here, che è anche costruito con Docma e ospitato su GitHub Pages.

Un campione screenshot del DOCMA generato SPA:

Answer 3

Anche se non ho aggiornato in un po ', https://github.com/punkave/dox-foundation è un'altra opzione. Genera solo file HTML che potresti impegnare nel tuo ramo gh-pages.

Answer 4

Sono un fanatico dello swagger: https://github.com/swagger-api/swagger-ui & http://swagger.io/.

Include molto più della semplice documentazione API, quindi forse è eccessivo per voi, ma fa un bel lavoro di documentazione delle API.

Answer 5

JSDox è esattamente quello che stai cercando.

Answer 6

cercando di semplificare

• Nelle pagine GitHub generare documentazione API che emette Jekyll markup.

  Modello di liquido di fuga con tag {% raw %}.

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

  ref: github/.com/Shopify/liquido/wiki/Liquid-for-Designers # prime

  Rif: jekyllrb/.com/docs/GitHub-pagine/# progetto-pagine

  creare due rami, uno per il master uno per gh-pages, il ramo master contiene il file .md e gh-pages contiene il file .html generato staticamente. Nel computer locale: $ jekyll build nella cartella del progetto corrente verrà generato in ./_site.

  caricare su GitHub.

  Jekyll

  • ramo principale: github/.com/Jekyll/Jekyll
  • gh-pagine ramo: github/.com/Jekyll/Jekyll/albero/GH-pagine

  fb/reagire

  • branch master: github/.com/facebook/reagire/modificare/master/docs/docs/ref-01-top -level-api.md
  • gh-pagine ramo: github/.com/facebook/reagire/blob/GH-pagine/docs/top-level-API.html

Gli URL di pagine si collegano al documento GitHub stesso.

In _layouts cartella (template HTML) Aggiungi link "Edit on GitHub" on docs pages questo è blog post about it