web-dev-qa-db-fra.com

Comment générer une documentation sur l'API JavaScript pour les pages GitHub

Il y a beaucoup d'excellentes options pour générer de la documentation d'API pour d'autres langues, mais je n'ai pas encore trouvé de solution pour mon API JavaScript que je souhaite héberger sur les pages GitHub. Il semble que je puisse utiliser JSDoc3 mais il me faudrait créer un plugin personnalisé qui produira un balisage Jekyll. 

J'aimerais également que les URL de code soient liées à GitHub lui-même. J'ai trouvé jsdoc-githubify qui va modifier la sortie pour modifier les liens, mais je préférerais une option plus simple, dans laquelle j'ai plus de contrôle.

Dois-je créer mon propre plug-in JSDoc, ou existe-t-il une meilleure solution que j'ai manquée? Qu'est-ce que les gens utilisent pour cela?

javascriptdocumentationjekyllgithub-pagesjsdoc
30
Andy Armstrong

Si vous connaissez (Grunt }, vous pouvez facilement générer des docs .html avec grunt-jsdoc . 

  • Documentez votre code avec JSDoc .
  • Utilisez grunt-jsdoc qui utilise en interne jsdoc pour générer la documentation de code.
  • Cela affichera également le code source au format HTML et inclura dans la documentation des liens vers des lignes de code pour chaque membre accessible au public.
  • Vous pouvez également avoir le contrôle sur les liens en utilisant simplement la directive @link de JSDoc:
    See {@link https://github.com/onury|My GitHub Profile}. 

Voir un exemple de Gruntfile ci-dessous.
Notez que cela prend en charge toutes les options de la CLI JSDoc .

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

Et vous exécutez cette tâche avec grunt jsdoc. Ou vous pouvez ajouter le plugin grunt-contrib-watch à exécuter automatiquement chaque fois que le fichier est modifié.

Modèles et style: 

  • Vous pouvez toujours jouer avec le fichier CSS et l'écraser à votre goût.
  • Ou vous pouvez utiliser le modèle docstrap pour JSDoc3 basé sur Bootstrap, qui peut être utilisé avec grunt-jsdoc.

Utilisation de Jekyll pour la documentation: 

Bien qu'il soit pris en charge de manière native, vous ne devez pas utiliser Jekyll pour les pages GitHub. Jekyll est en fait conçu pour les sites Web statiques ou les blogs. Mais cela peut prendre des fichiers de démarques. Donc, je commencerais par créer des fichiers de démarques github à partir de code via jsdoc-to-markdown (il y a également un plugin Grunt grunt-jsdoc2md ), puis configurer un projet Jekyll en conséquence. 

Notez cependant que vous devrez effectuer des tâches supplémentaires pour installer et configurer Jekyll. Voici un bon article et un exemple de projet pour commencer. 

METTRE À JOUR: 

Après avoir répondu à cette question, j'ai commencé à travailler sur un outil permettant de créer facilement de la documentation. Maintenant, il est assez mature pour poster ici et voir si vous l’aimez. Cela s'appelle Docma . 

Les principales caractéristiques de Docma sont: il peut analyser les fichiers JSDoc et Markdown dans une documentation HTML, génère une application Web extrêmement configurable et fonctionne parfaitement avec Github Pages.

Voir Documentation Docma ici }, qui est également construit avec Docma et hébergé sur GitHub Pages.

Un exemple de capture d'écran de SPA généré par Docma:

enter image description here

20
Onur Yıldırım

Je pense que c’est ce que vous recherchez: http://jsdox.org/

jsdox est un simple générateur de jsdoc 3. Il extrait les balises de documentation basées sur un sous-ensemble de jsdoc 3 de vos fichiers javascript et génère des fichiers de démarquage.

5
Xavi Magrinyà

JSDox est exactement ce que vous recherchez.

2
Charlie H

Je suis fan de swagger: https://github.com/swagger-api/swagger-ui & http://swagger.io/ . 

Cela inclut plus que de la documentation sur les API, alors c'est peut-être un peu trop pour vous, mais vous documentez bien les API. 

1
obi1

essayant de le simplifier

  • Dans les pages GitHub générant la documentation de l'API qui génère le balisage Jekyll

    </ p>

    Échappez le modèle liquide avec la balise {% raw %}.

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

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

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

    créez deux branches, une pour maître, une pour gh-pages, master branche contenant votre fichier .md et gh-pages contenant un fichier .html généré de manière statique. Sur l'ordinateur local: $ jekyll build dans le dossier du projet en cours sera généré dans ./_site.

    télécharger sur GitHub.

    jekyll

    • branche principale: github/.com/jekyll/jekyll
    • branche gh-pages: github/.com/jekyll/jekyll/arbre/gh-pages</ p></ blockquote>

      fb/réagir

      • branche principale: github/.com/facebook/réagir/modifier/maître/docs/docs/ref-01-top-level-api.md
      • branche gh-pages: github/.com/facebook/react/blob/gh-pages/docs/top-level-api.html
    </ li>

  • Les URL Pages renvoient au document GitHub lui-même.

    Dans le dossier _layouts (modèle html) Ajouter un lien "Modifier sur GitHub" sur les pages de documentation ceci est l'article de blog à ce sujet

    • </ ul>

0
blinksmith

Bien que je ne l'ait pas mis à jour depuis un moment, https://github.com/punkave/dox-foundation est une autre option. Il ne fera que générer des fichiers HTML que vous pourriez valider dans votre branche gh-pages. 

0
mattmcmanus