it-swarm.xyz

Как я могу сгенерировать документацию JavaScript API для GitHub Pages

Существует множество отличных возможностей для создания документации API для других языков, но мне еще предстоит найти решение для моего JavaScript API, которое я хочу разместить на страницах GitHub. Кажется, что я могу использовать JSDoc3 , но мне нужно создать собственный плагин, который выводит разметку Jekyll. 

Я также хотел бы, чтобы URL-адреса кода ссылались на сам GitHub. Я нашел jsdoc-githubify , который изменяет вывод для изменения ссылок, но я бы предпочел более простой вариант, где у меня больше контроля.

Нужно ли мне создавать свой собственный плагин JSDoc, или есть лучшее решение, которое я пропустил. Что люди используют для этого?

30
Andy Armstrong

Если вы знакомы с Grunt , вы можете легко сгенерировать документы .html с помощью grunt-jsdoc

  • Документируйте свой код с помощью JSDoc .
  • Используйте grunt-jsdoc который внутренне использует jsdoc для генерации документации кода.
  • Это также выведет исходный код в HTML и в документацию будет включать ссылки на строки кода для каждого общедоступного члена.
  • Вы также можете контролировать ссылки, просто используя директиву @link в JSDoc:
    See {@link https://github.com/onury|My GitHub Profile}

Смотрите пример Gruntfile ниже.
Обратите внимание, что это поддерживает все параметры JSDoc CLI .

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

И вы запускаете эту задачу с помощью grunt jsdoc. Или вы можете добавить плагин grunt-contrib-watch для автоматического запуска при каждом изменении файла.

Шаблоны и стили: 

  • Вы всегда можете поиграть с CSS-файлом и перезаписать его на свой вкус.
  • Или вы можете использовать docstrap template для JSDoc3 на основе Bootstrap, который можно использовать с grunt-jsdoc.

Использование Jekyll для документации: 

Хотя он изначально поддерживается, вам не нужно использовать Jekyll для страниц GitHub. Jekyll на самом деле предназначен для статических сайтов или блогов. Но это может занять файлы уценки. Итак, я бы сначала создал файлы разметки со вкусом github из кода через jsdoc-to-markdown (есть также плагин Grunt grunt-jsdoc2md ), а затем configure проект Jekyll соответственно. 

Но учтите, что вам нужно проделать дополнительную работу для установки и настройки Jekyll. Вот хорошая статья и пример проекта для начала. 

Обновление: 

После ответа я начал работать над инструментом для создания документации. Теперь он достаточно зрелый, чтобы размещать здесь сообщения и смотреть, нравится ли вам это. Это называется Docma

Ключевые особенности Docma: он может анализировать файлы JSDoc и Markdown в HTML-документации, генерировать веб-приложение, чрезвычайно настраиваемый и прекрасно работает с Github Pages.

Смотрите Документация по Docma здесь , которая также построена с помощью Docma и размещена на страницах GitHub.

Пример снимка экрана сгенерированного Docma SPA:

 enter image description here

20
Onur Yıldırım

Я думаю, это то, что вы ищете: http://jsdox.org/

jsdox - это простой генератор jsdoc 3. Он извлекает теги документации на основе подмножества jsdoc 3 из ваших файлов javascript и генерирует файлы уценки.

5
Xavi Magrinyà

JSDox это именно то, что вы ищете.

2
Charlie H

Я фанат чванства: https://github.com/swagger-api/swagger-ui & http://swagger.io/

Он включает в себя не только документацию по API, поэтому, может быть, это излишне для вас, но он прекрасно справляется с документированием API. 

1
obi1

пытаясь упростить это

  • На страницах GitHub, генерирующих документацию API, которая выводит разметку Jekyll.

    </ Р>

    Шаблон Escape Liquid с тегом {% raw %}.

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

    ref: github/.com/Shopify/жидкость/вики/жидкость для дизайнеров # raw

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

    создайте две ветви, одну для главной, одну для gh-страниц, главную ветвь, содержащую ваш файл .md, и gh-страницы, содержащие статический сгенерированный файл .html. На локальном компьютере: $ jekyll build в папке текущего проекта будет сгенерирован в ./_site.

    загрузить на GitHub.

    джекил

    • основная ветка: github/.com/jekyll/jekyll
    • ветвь gh-pages: github/.com/jekyll/jekyll/tree/gh-pages</ Р></ BLOCKQUOTE>

      fB/реагируют

      • главная ветка: github/.com/facebook/реагировать/редактировать/master/docs/docs/ref-01-top-level-api.md
      • ветка gh-pages: github/.com/facebook/реакции/blob/gh-pages/docs/top-level-api.html
    </ Li>
  • Страницы URL-адреса ссылаются на сам документ GitHub.

    В папке _layouts (html template) Добавить ссылку «Редактировать на GitHub» на страницах документов это сообщение в блоге об этом

  • </ UL>

0
blinksmith

Хотя я давно не обновлял его, https://github.com/punkave/dox-foundation это еще один вариант. Он просто сгенерирует HTML-файлы, которые вы можете зафиксировать в своей ветке gh-pages

0
mattmcmanus