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

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

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

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

Ответ 1

Если вы знакомы с Grunt, вы можете легко сгенерировать .html docs с помощью 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 шаблон для JSDoc3 на основе Bootstrap, который можно использовать с grunt-jsdoc.

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

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

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

ОБНОВЛЕНИЕ:

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

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

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

Пример скриншота созданного Docma SPA:

Ответ 2

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

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

Ответ 3

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

Ответ 4

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

Ответ 5

Я поклонник чванства: https://github.com/swagger-api/swagger-ui и http://swagger.io/.

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

Ответ 6

пытается упростить его

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

Сбросьте шаблон жидкости с тегом {% raw %}.
```
{% raw %}
   I want to be {{escaped}}.
{% endraw %}
```
ref: github/.com/Shopify/liquid/wiki/Liquid-for-Designers # raw

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

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

загрузить в GitHub.
Джекил
- главная ветка: github/.com/jekyll/jekyll
- ветвь gh-pages: github/.com/jekyll/jekyll/tree/gh-pages
FB/реагируют
- главная ветка: github/.com/facebook/реакция/редактирование/master/docs/docs/ref-01-top-level-api.md
- ветвь gh-pages: github/.com/facebook/response/blob/gh-pages/docs/top-level-api.html

URL страниц ссылается на сам документ GitHub.

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