Мой подход к документированию проектов на Javascript
В этой короткой статье я поделюсь с вами своим недавним опытом документирования кода JavaScript. Я пришел к довольно интересному решению с использованием JSDocs, которое может быть применено практически к любому javascript — приложению среднего размера.
Чтобы увидеть, то чем я говорю, вы можете посмотреть на: https://softwarebrothers.github.io/admin-bro-dev/index.html и связанный репозиторий GitHub: https://github.com/SoftwareBrothers/admin-bro-dev
Так что если у вас есть приложение, где:
- Фронтенд написан на React/Angular/Vue/Vanilla
- API написано на Node.js
- И у вас также есть пара (микро) сервисов, написанных на JavaScript …
…то эта статья для вас.
Я не буду рассказывать вам о том, как установить JSDoc в вашем проекте и что означает каждый тег JSDoc. Я скорее опишу идею верхнего уровня настройки JSDoc для полного документирования всего проекта. Вы всегда можете посетить мой канал на YouTube и посмотреть 2 эпизода о JSDocs и better-docs.
Но прежде чем мы углубимся в детали — давайте поговорим о: «зачем это нужно?
Какую проблему решает документирование — или зачем нам нужна документация?
Я участвую в нескольких ИТ-проектах уже десять лет, и всегда требовалась какая-то документация по нескольким причинам:
- Чтобы хранить и делиться «внутренней» информацией о системе, описания часто используемых терминов и т. д.
- Для описания архитектуры высокого уровня — какой сервис за что отвечает.
- Для описания деталей реализации низкого уровня — каковы цели данных Class/Module, описания их интерфейсов и объяснения того, как их использовать
В этой статье я хотел бы рассказать вам, как я решил эти проблемы в одном из моих недавних проектов. Все будет сгруппировано в 6 простых концепций.
6 Концепций
Концепция №. 1: Корневой репозитарий
Обычно «Архитектура приложения» и «Знание бизнеса (Business Knowledge)» — это термины, которые относятся ко всем службам в приложении. Вот почему мне нужно было одно место, где я мог бы разместить всю информацию, касающуюся этих 2 моментов.
Поскольку я использовал JSDocs, я собрал весь код в одном репо с помощью git submodule (https://git-scm.com/book/en/v2/Git-Tools-Submodules) — я буду называть его root repo.
Проще говоря, git submodules позволяют вам связывать одно хранилище с другим.
Это структура основной папки моего корневого хранилища:
(git submodule) /fronted (git submodule) /api (git submodule) /microservice1 (git submodule) /microservice2 /infrastructure /docs-src /docs package.json readme.md etc
В /infrastructure я храню все файлы, связанные с docker и docker-compose.
/docs-src содержит файлы, используемые JSDoc, не обязательно связанные с кодом, такие как статические файлы (изображения, screenshots) и учебные пособия (markdown).
/docs — это место, где хранится актуальная документация.
ОК — вот как я создал несколько репозиториев. Затем я установил JSDoc3 в корневом репозитории (поэтому там есть файл package.json)
Концепция № . 2: JSDOC
Теория:
JSDoc — это язык разметки, используемый для описания кода, написанного на javascript. Он выглядит примерно так:
/**
* Finds one Record in the Resource by its id
* @param {String} id uniq id of the Resource Record
* @return {Promise<BaseRecord>} record
* @abstract
*/
async findOne(id) {
//...
}
В приведенном выше примере мы описали функцию findOne:
- что она на самом деле делает
- какие аргументы принимает
- что возвращает
- и указали что это абстрактный метод
JSDoc3, с другой стороны, это инструмент, который считывает все комментарии JSDoc и генерирует из них HTML-документацию.
Мой подход:
Каждый репозиторий (включенный как submodule) имеет свои собственные комментарии JSDoc. JSDoc3 можно передать файл конфигурации, в котором я определил, что:
- вся документация должна быть генерируется в папку /docs
- JSDoc должен прочитать все git submodules
- место, куда я положу мои уроки, будет /docs-src (читайте следующий пункт)
…и кучу других параметров.
Концепция №. 3: учебники JSDOC
JSDoc сам по себе создает очень хорошую низкоуровневую документацию для классов, модулей и т. д. Но он также позволяет добавлять пользовательские файлы markdown — они называются «учебниками».
Вот почему я создал папку /docs-src в корневом репозитории — это место, где я размещаю файлы учебников.
Учебники очень полезны, когда речь идет о хранении «Бизнес-знаний». Там вы можете описать общую архитектуру, инструкции по установке, отношения между сервисами, моделями баз данных и т. д.
Взгляните на разделы учебников, которые я создал: https://softwarebrothers.github.io/admin-bro-dev
Концепция №. 4: Графики с MERMAID
Следующее, что я использовал, были графики, созданные с помощью Mermaid. По сути, вы можете добавить график в комментарии JSDocs с помощью тега @mermaid (доступно через плагин mermaid jsdoc).
Я также добавил несколько графиков в уроки со следующим хаком:
### Regular Markdown
Since markdown allows you to insert HTML, this is what you can do:
<div class="mermaid">
graph LR
A[BaseDatabase] -->|has many| B(BaseResource)
B --> |has many|C(BaseRecord)
B --> |has many|D(BaseProperty)
</div>
At the end of the file you also have to include mermaid:
<script src="https://cdn.rawgit.com/knsv/mermaid/7.0.0/dist/mermaid.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.rawgit.com/knsv/mermaid/7.0.0/dist/mermaid.css">
<script>mermaid.initialize({ startOnLoad: true });</script>
Концепция №. 5: Внешний вид документации
По умолчанию JSDoc3 генерирует документацию, которая выглядит следующим образом.
Я попытался найти хорошую тему, которую мог бы использовать (на странице JSDoc GitHub есть пара ссылок на разные шаблоны), но в конце концов я решил попросить одного из наших дизайнеров пользовательского интерфейса создать что-то очень простое, но очень удобное для пользователя. дружелюбный.
Наша тема называется better-docs и может быть найдена здесь: https://github.com/SoftwareBrothers/better-docs
И вот как выглядит та же самая документация:
Концепция №. 6: Группировка с помощью @CATEGORY
Когда я настроил JSDoc для анализа всех git submodules, у меня появилась «не очень хорошо организованная» документация (она была абсолютно запутанной). Поэтому я решил написать крошечный плагин JSDoc, который группирует вещи по категориям — он включен в ранее упомянутые better-doc.
Короче говоря, используя его, вы можете разделить документацию по категориям на боковой панели. Опять же — взгляните на https://softwarebrothers.github.io/admin-bro-dev/index.html — где Adapter, Decorators, Errors и PropertyTypes являются категориями.
И это была последняя из 6 концепций, которые я использовал. Все эти вещи не очень новаторские, но в сочетании они создают очень мощный набор инструментов для документации.
Развертывание
Существует несколько вариантов развертывания документации, сгенерированной JSDoc. Самые очевидные из них:
- Опубликуйте это в AWS S3 bucket и хост как статическую страницу
- Сгенерируйте документацию на каком нибудь вашем сервере и настройте Nginx/Apache для его размещения.
- Используйте GitHub (или BitBucket)
В прошлый раз я использовал третий вариант — поэтому я создал папку /docs внутри корневого репозитория для хранения документации. Вы можете настроить GitHub для использования в качестве источника публикации, и это стоит того чтобы проверить.
После того как вы сгенерировали документацию в исходном коде, помните, что вы должны время от времени обновлять ее. Подумайте о своих коллегах, которые получают PullRequests с 20 файлами обновленной HTML-документации — как минимум они будут разочарованы … :).
Наличие отдельного корневого репозитория для документации решает эту проблему — фиксации кода остаются внутри подмодулей, и PR, обновляющие сгенерированную документацию, отправляются в корневое репо.
Заключение
До сих пор я использовал эту структуру в 3 проектах, и она работает довольно хорошо.
Я, наверное, уже упоминал об этом пару раз, но вы можете увидеть рабочий пример здесь:
- Исходный код: https://github.com/SoftwareBrothers/admin-bro-dev
- Актуальная документация: https://softwarebrothers.github.io/admin-bro-dev/
Надеюсь, вы нашли статью полезной, а некоторые советы, которыми я поделился, облегчат вашу жизнь разработчика.
Вы также можете следить за мной в твиттере, где я публикую последние новости о наших библиотеках.
Оригинальная статья: Wojciech Krysiak — MY APPROACH TO DOCUMENTING JAVASCRIPT PROJECTS