Jak wygenerować dokumentację JavaScript API dla GitHub Pages

Question

Istnieje wiele wspaniałych opcji generowania dokumentacji API dla innych języków, ale muszę jeszcze znaleźć rozwiązanie dla mojego JavaScript API, które chcę hostować na stronach GitHub. Wygląda na to, że mogę używać JSDoc3, ale potrzebuję stworzyć niestandardową wtyczkę, która generuje znaczniki Jekyll.

Chciałbym również, aby adresy URL kodu prowadziły do ​​samego GitHub. Znalazłem jsdoc-githubify, który zmodyfikuje dane wyjściowe, aby zmienić linki, ale wolę bardziej prostą opcję, w której mam większą kontrolę.

Czy muszę utworzyć własną wtyczkę JSDoc, czy istnieje lepsze rozwiązanie, które przeoczyłem. Co ludzie używają do tego?

Answer 1

myślę, że to jest to, czego szukasz: http://jsdox.org/

jsdox jest prosty JSDoc 3 generator. Wyciąga znaczniki dokumentacji na podstawie podzbioru jsdoc 3 z plików javascript i generuje pliki ze znacznikami.

Answer 2

Jeśli jesteś zaznajomiony z Grunt można łatwo wygenerować .html dokumenty z grunt-jsdoc.

• Dokumentuj swój kod za pomocą JSDoc.
• Użyj grunt-jsdoc, która wewnętrznie używa jsdoc do generowania dokumentacji kodu.
• Spowoduje to również wyprowadzenie kodu źródłowego w HTML oraz w dokumentacji, która będzie zawierać linki do linii kodu dla każdego publicznie dostępnego członka.
• Możesz także kontrolować linki za pomocą dyrektywy @link JSDoc:
  See {@link https://github.com/onury|My GitHub Profile}.

Zobacz przykład Gruntfile poniżej.
Należy pamiętać, że obsługuje to wszystkie JSDoc CLI options.

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

Wykonujesz to zadanie z grunt jsdoc. Lub możesz dodać wtyczkę grunt-contrib-watch, aby automatycznie uruchamiać się za każdym razem, gdy plik się zmieni.

Szablony i Stylizacja:

• Zawsze można grać z pliku CSS i zastąpić go dla własnego smaku.
• Lub możesz użyć szablonu docstrap dla JSDoc3 na podstawie Bootstrap, który może być używany z grunt-jsdoc.

Korzystanie Jekyll dokumentacji:

Mimo to natywnie obsługiwany, nie trzeba używać Jekyll na GitHub Pages. Jekyll jest rzeczywiście zaprojektowany do statycznych stron internetowych lub blogów. Ale może pobrać pliki ze zniżkami.Tak więc, najpierw utworzę pliki oznaczania smaku github z kodu poprzez jsdoc-to-markdown (istnieje również wtyczka Grunt grunt-jsdoc2md), a następnie configure projekt Jekyll odpowiednio.

Należy jednak pamiętać, że aby zainstalować i skonfigurować Jekyll, należy wykonać dodatkowe czynności. Tutaj jest dobry article i sample project na początek.

UPDATE:

Po odebraniu tego, zacząłem pracować na narzędzie do dokumentacji budowy łatwo. Teraz jest wystarczająco dojrzały, aby opublikować tutaj i sprawdzić, czy Ci się to podoba. Nazywa się Docma.

Najważniejsze cechy Docmy to; może zarówno parsować pliki JSDoc i Markdown do dokumentacji HTML, generuje aplikację internetową, wyjątkowo konfigurowalną i współpracuje z Github Pages.

Patrz: Docma documentation here, który jest również zbudowany z Docma i hostowany na stronach GitHub.

Przykładowy zrzut ekranu DOCMA generowane SPA:

Answer 3

Choć nie zostały zaktualizowane go na jakiś czas, https://github.com/punkave/dox-foundation ma innej opcji. Po prostu wygeneruje pliki HTML, które możesz zatwierdzić w swoim oddziale gh-pages.

Answer 4

Jestem fanem oszołomienia: https://github.com/swagger-api/swagger-ui & http://swagger.io/.

Zawiera więcej niż tylko dokumentację interfejsu API, więc może to dla ciebie przesada, ale ma ona piękne zadanie dokumentowania interfejsów API.

Answer 5

JSDox jest dokładnie tym, czego szukasz.

Answer 6

próbuje uprościć

• na stronach GitHub generowania dokumentacji API, która wyprowadza Jekyll znaczników.

  Płynny szablon Escape z tagiem {% raw %}.

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

  ref: github/com/Shopify/ciecz/wiki/Liquid-for-projektantów # surowe

  Ref: jekyllrb/com/docs/GitHub-pages/# project-pages

  utwórz dwie gałęzie, jedną dla głównego dla strony gh, gałąź główna zawiera plik .md, a strony gh zawierają statyczny plik .html. W komputerze lokalnym: $ jekyll build w bieżącym folderze projektu zostanie wygenerowany do ./_site.

  przesłać na GitHub.

  Jekyll

  • mistrz Branża: github/com/Jekyll/Jekyll
  • GH-pages Branża: github/com/Jekyll/Jekyll/tree/GH-pages

  fb/reagują

  • mistrz Branża: github/com/facebook/reagują/edit/master/docs/docs/ref-01-top -level-api.md
  • gH strony gałęzi: GitHub/com/facebook/reakcji/kropelka/GH stron/Docs/najwyższego poziomu, api.html

Adresy URL stron link do samego dokumentu GitHub.

W _layouts folderu (szablonu HTML) Dodaj link "Edit on GitHub" on docs pages to blog post about it