Создание документации API для пакетов TypeScript с помощью TypeDoc

Лучшая документация для лучшего обслуживания пользователей вашего пакета

С помощью TypeDoc можно добавлять структурированные комментарии (комментарии в стиле JSDoc) к исходному коду TypeScript. Используя данные в этих комментариях, TypeDoc создает хорошую документацию по API, которую вы можете легко опубликовать на веб-сайте. С добавлением еще одного инструмента, gh-pages, документацию на GitHub Pages легко опубликовать.

Важно опубликовать API в пакете, показав функции, параметры методов, типы данных и т. д. Пользователи вашего API должны знать, какие функции доступны и т. д. Это помогает им набрать скорость и использовать ваш API. Чем полнее документация по API, тем лучше.

Это делает лучшей практикой публиковать качественную документацию по API.

К сожалению, для большинства пакетов JavaScript документация по API не является исчерпывающей. Как пользователь многих пакетов Node.js, меня часто раздражает схематичное описание API. Я предполагаю, что проекты, в которых отсутствует хорошая документация по API, не знали об инструментах, которые упрощают создание документации по API. Я сам в этом виноват в своих же пакетах, и просто не знал о таких инструментах. Это заставило меня создавать документацию по API вручную, что, конечно, не лучшая практика.

В этой статье мы рассмотрим использование TypeDoc для публикации качественной документации API для пакета TypeScript.

Я пишу это сразу после создания веб-сайта с документацией по API для моего последнего проекта. Мы будем использовать это как практический пример.

• https://runtime-data-validation-js.github.io/ — пакет runtime-data-validation представляет собой набор декораторов TypeScript для обеспечения достоверности данных.
• https://runtime-data-validation-js.github.io/runtime-data-validation-typescript/ — это документация API для этого пакета.
• https://github.com/runtime-data-validation-js/runtime-data-validation-typescript — Исходный код пакета. Найдите в каталоге api процесс создания сайта API.
• https://github.com/runtime-data-validation-js/runtime-data-validation-js.github.io — Исходный код сайта.

Структурированные комментарии JSDoc, TSDOC и TypeDoc

Одним из стандартных инструментов для документации API JavaScript является JSDoc, но он не поддерживает создание документации для кода TypeScript. Подход JSDoc использует такие структурированные комментарии:

/**
 * Description of the purpose or results of the function. 
 *
 * @param target Documentation for parameter 'target' 
 * @param text   Documentation for parameter ´text´. 
 * @return Comment about return value 
 */ 
function doSomething(target: any, text: string): number {
     // code 
}

TSDoc — это предложение стандартных тегов комментариев для использования в TypeScript. Это не инструмент для создания документации, а стандартный список тегов.

TypeDoc — это инструмент, похожий на JSDoc, но поддерживающий TypeScript. Это отличный инструмент для подробной документации, в которой четко изложены такие детали, как параметры функций, типы возвращаемых значений и многое другое. Он использует тот же тип структурированных комментариев, что и JSDoc, и поддерживает подмножество тегов комментариев TSDoc/JSDoc.

Комментарии в стиле JSDoc, используемые TypeDoc, имеют согласованную структуру, которая помогает прояснить структуру кода, делая сами комментарии полезным дополнением к вашему коду. Кроме того, среда IDE, например Visual Studio Code, может отображать информацию из этих комментариев во всплывающих окнах при редактировании кода.

Подобные структурированные комментарии используются во многих языках.

Если вы опустите структурированные комментарии, компилятор TypeScript сможет вывести большую часть информации. Но, используя комментарии, вы можете добавить свои собственные описания для еще лучшего результата.

Установка TypeDoc в проекте TypeScript

Поскольку и TypeScript, и TypeDoc являются инструментами Node.js, вы должны сначала установить Node.js. Поскольку подавляющее большинство людей, читающих это, уже знают об этом, я предполагаю, что он у вас уже установлен. Если нет, прочтите: Настройка компилятора Typescript для интеграции с разработкой Node.js

Чтобы запустить пустой проект TypeScript:

$ npm init -y 
$ npm install typescript @types/node --save-dev

Теперь вы можете ввести это, чтобы увидеть инструкции по использованию:

$ npx tsc --help

Это подтверждает, что TypeScript установлен и работает.

Следующим шагом является файл конфигурации TypeScript, tsconfig.json. Поскольку вы, вероятно, уже являетесь программистом TypeScript, вы, вероятно, уже настроили эту конфигурацию. Типичная конфигурация заключается в том, чтобы хранить исходный код TypeScript в одном каталоге, например src, а для TypeScript создавать файлы в другом каталоге, например dist или build.

Чтобы установить TypeDoc, выполните следующую команду:

$ npm install typedoc --save-dev

Это установит TypeDoc, сохранив его в файле devDependencies.

Поскольку TypeDoc создает веб-сайт, полезно иметь локальный HTTP-сервер, чтобы вы могли локально просматривать документацию.

$ npm install @compodoc/live-server --save-dev

Этот конкретный сервер очень хорош, включает перезагрузку в реальном времени при изменении контента и другие полезные функции.

Краткое руководство по использованию TypeDoc в проекте TypeScript

В качестве быстрого эксперимента запустите эту команду:

$ npx typedoc --out api src/index.ts 
$ npm live-preview api

Эта команда предполагает, что ваш исходный код TypeScript находится в каталоге src. Для TypeDoc не имеет значения, в каком каталоге находится собранный код JavaScript, поскольку он читает исходники TypeScript.

Это создает документацию в каталоге api, начиная с определенного исходного файла. Замените здесь любой исходный файл, который является основной точкой входа для вашего пакета.

Это документация API по умолчанию, созданная для пакета runtime-data-validation.

Основной раздел взят из проекта README. Список функций на боковой панели — это API. Вверху находится пара подмодулей, входящих в комплект.

Для этой версии документация не была изменена.

Это документация для одной из функций в пакете. Этот пакет предназначен для проверки данных и, следовательно, для описания параметров и результатов одной из функций декоратора проверки.

Очевидно, что это документация по API хорошего качества. Параметры функции и результаты четко и организованно описаны. У нас есть места, чтобы положить наши слова. Существует ссылка на исходный код, которая напрямую связана с репозиторием GitHub.

Но при ближайшем рассмотрении результата я обнаружил ряд вещей, которые нужно изменить.

• Переход обратно на основной веб-сайт проекта со страниц документации по API.
• Использование текста, отличного от README проекта
• Если на странице документации, как вернуться на главную страницу API
• Наличие обзорной документации любых подмодулей
• TypeDoc плохо представляет документацию декораторов TypeScript. runtime-data-validation содержит длинный список функций-декораторов, но читатель API не знает, что эти функции являются функциями-декораторами. Я не смог найти хорошее решение для этой проблемы.

TypeDoc предлагает несколько способов настройки вывода, так что давайте посмотрим.

Настройка пакета TypeScript для использования TypeDoc

Самый эффективный способ настройки TypeDoc — с помощью файла конфигурации. Все параметры можно использовать в командной строке, но это быстро становится очень длинным.

Создайте файл с именем typedoc.json, который будет содержать конфигурацию. Начните с этого:

{
     "customTitle": "runtime-data-validation-js.github.io",
     "customTitleLink": "https://runtime-data-validation-js.github.io/",
     "name": "Runtime data validation for TypeScript",
     "includeVersion": true,
     "hideGenerator": true,
     "out": "api",
     "readme": "README-api.md",
     ... 
}

Свойство out указывает выходной каталог.

Свойство readme переопределяет файл README по умолчанию, используемый для документации главной страницы. README проекта уже есть в репозитории GitHub и на странице npmjs.com. Почему люди должны читать одну и ту же документацию в третий раз. Почему бы вместо этого не использовать здесь текст, полезный для тех, кто читает документацию по API, например совет по использованию документации.

Это дает некоторые полезные навигационные улучшения.

Плагины и темы для TypeDoc

TypeDoc предлагает два пути для более глубокой настройки:

• Темы переопределяют представление документации API по умолчанию. Например, в одной теме документация выводится в виде файлов Markdown.
• Плагины могут вносить другие изменения

В случае с проектом runtime-data-validation я решил не разрабатывать собственную тему, а установил только один плагин. На создание пользовательской темы ушло бы некоторое время, а тема по умолчанию довольно хороша.

Для установки: npm install typedoc-plugin-extras --save-dev

Чтобы создать документацию API между файлом конфигурации и плагином:

$ npx typedoc --plugin typedoc-plugin-extras --options typedoc.json ./src/index.ts

Параметр --plugin включает плагины, а --option использует файл параметров.

Полезные комментарии к документации

При разработке документации API для проекта runtime-data-validation я выбрал следующие особенности комментариев JSDoc/TypeDoc.

Категории позволяют организовать функции или другие объекты в группы. Имена категорий имеют свободную форму, и вы выбираете названия категорий, которые вам понятны.

/**
 * @category Finance Validator
 */

Например, проект runtime-data-validation содержит длинный список функций проверки данных. Это привело к нескольким категориям для того или иного типа функций проверки.

Ссылки на внешнюю документацию включаются с помощью тега {@link}.

/** 
 * check if the string is a valid RFC 3339 date. 
 * {@link https://tools.ietf.org/html/rfc3339} 
 *  
 * @param value The string to validate 
 * @returns  
 * @category Date Validator  
 */

Таким образом, пользователи вашего API могут быстро найти что-то в официальной документации.

Ссылки на внутренние типы также включаются с помощью тега {@link}.

/** 
 * Check if the input is a valid ISO8601 date.  
 *  
 * @param value The string to validate 
 * @param options {@link IsISO8601Options} 
 * @returns  
 * @category Date Validator 
 */

В этом случае был определен отдельный тип для использования в качестве параметра функции. Это удобная ссылка на этот тип.

Комментарии к модулю позволяют дать обзорную документацию по группе функций или классов.

/** 
 * Overview documentation for a module. 
 * @module module-name 
 */

Ссылка в стиле Markdown над тегом @module — это удобная ссылка на главную страницу документации по API. Таким образом, читатели вашего API смогут легче ориентироваться. Почему-то в TypeDoc нет ссылки на главную страницу.

Публикация документации API для общего пользования

Конечно, цель этого — опубликовать документацию по API в месте, где люди смогут ее прочитать. Поговорим о некоторых практических способах сделать это. Мы будем использовать метод, который я использовал для runtime-data-validation-js.github.io в качестве примера.

Используя команду typedoc, мы можем создать каталог, полный файлов HTML, JavaScript и CSS. Но как лучше всего сделать правильный веб-сайт, используя эти файлы? Ваш ответ, конечно, зависит от вас. В моем случае я создал генератор статических веб-сайтов (AkashaCMS) и с его помощью легко публикую веб-сайты на страницах GitHub. GitHub Pages — это функция GitHub, с помощью которой вы можете назначить ветку в своем репозитории для отображения в качестве веб-сайта.

Сначала я создал организацию GitHub runtime-data-validation-js для размещения проекта. Репозиторий runtime-data-validation-js.github.io содержит код AkashaCMS для создания веб-сайта, который виден по адресу https://runtime-data-validation-js.github.io.

Сайт содержит документацию по использованию пакета, а также блог. Для целей этого обсуждения давайте сосредоточимся на панели навигации:

Это основная панель навигации, которая отображается на каждой странице. Например, поле Поиск использует DuckDuckGo в качестве поисковой системы для конкретного сайта. Реализация панели навигации — это обычная панель навигации Bootstrap. Важной особенностью является ссылка с именем API, которая является ссылкой на документацию в том виде, в каком она опубликована с использованием страниц GitHub. Это означает, что у людей, читающих веб-сайт, есть простой способ получить доступ к документации API, просто щелкнув ссылку API.

Документация API генерируется кодом в репозитории GitHub для пакета runtime-data-validation. Это обычный повседневный репозиторий GitHub для проекта TypeScript. Для этого обсуждения сосредоточьтесь на каталоге api, где есть подпроект, посвященный задаче создания документации API. В этом каталоге находится package.json, который содержит scripts записей для управления процессом сборки и публикации.

"scripts": {
     "build": "npx typedoc --plugin typedoc-plugin-extras --options typedoc.json ../lib/index.ts",
     "publish": "npx gh-pages -b gh-pages -d site",
     "preview": "live-server site" 
},

Вы видите, что build запускает typedoc для построения HTML, а preview запускает live-server для локального предварительного просмотра. Шаг build ссылается на ../lib/index.ts как на точку входа, потому что именно там находится файл относительно каталога api.

Сценарий publish использует gh-pages для публикации на страницах GitHub. Инструмент gh-pages — это API для публикации на страницах GitHub, а также инструмент командной строки. Он позаботится обо всем, что необходимо для публикации HTML с помощью GitHub Pages.

В этом случае документация API встроена в каталог с именем site. Параметр -b gh-pages означает, что содержимое каталога site помещается в ветку gh-pages главного репозитория.

Краткое содержание

TypeDoc очень легко использовать для создания действительно хорошей документации API для вашего проекта TypeScript.

С gh-pages очень легко опубликовать эту документацию на страницах GitHub.

об авторе

Дэвид Херрон: Дэвид Херрон — писатель и инженер-программист, занимающийся вопросами разумного использования технологий. Его особенно интересуют экологически чистые энергетические технологии, такие как солнечная энергия, энергия ветра и электромобили. Дэвид почти 30 лет работал в Силиконовой долине над программным обеспечением, начиная от систем электронной почты и заканчивая потоковым видео и языком программирования Java, и опубликовал несколько книг о программировании Node.js и электромобилях.

Первоначально опубликовано на https://techsparx.com.