bem-data-source
Данный инструмент предназначен для публикации данных документации и примеров по библиотекам блоков.
bem-data-source может быть использован в двух различных режимах работы:
- Как самостоятельная nodejs cli утилита
- Как npm зависимость для nodejs приложения
Работа c bem-data-source в режиме консольной утилиты
Установка
- клонировать репозиторий
git clone git://github.com/bem/bem-data-source.git
- перейти в директорию со скаченным проектом
cd bem-data-source
- установить npm зависимости коммандой
npm install
- сгенерировать приватный конфигурационный файл командой
npm run config
. (После выполненияnpm run config
должен появиться новый конфигурационный файлconfig/private.json
).
Конфигурирование
Конфигурация инструмента описывается в файлах config/public.json
, config/private.json
.
Файл config/public.json
logLevel
- флаг уровня логгирования. может принимать значения: ("verbose", "debug", "info", "warn", "error")languages
- массив локалейmaxOpenFiles
- максимальное количество открытых файлов. Этот параметр также определяет размер порций файлов которые одновременно записываются в хранилище.
Файл config/private.json
storage
- объект с конфигурацией для хранилища.
storage: {
"common": {
"namespace": "your namespace", //пространство имен в хранилище
"get": {},
"post": {},
"auth": "", //уникальный заголовок авторизации. Необходим для выполнения запросов по модификации данных
"debug": false, //флаг включающий дополнительное логгирование операций по работе с удаленных хранилищем
"timeout": 300000 //максимально допустимое время выполнения запросов (в миллисекундах)
},
"testing": { //тестовая конфигурация хранилища
"get": {
"host": "testing host for read data", //тестовый хост хранилища для чтения данных
"port": 80 //тестовый порт хранилища для чтения данных
},
"post": {
"host": "testing host for modify data", //тестовый хост хранилища для изменения данных
"port": 1111 //тестовый хост хранилища для изменения данных
}
},
"production": { //боевая конфигурация хранилища
"get": {
"host": "production host for read data", //боевой хост хранилища для чтения данных
"port": 80 //боевой порт хранилища для чтения данных
},
"post": {
"host": "production host for modify data", //боевой хост хранилища для изменения данных
"port": 1111 //боевой порт хранилища для изменения данных
}
}
}
mailer
- объект с настройками почтовой рассылки.
{
"mailer": {
"host": "your e-mail-host", //хост smtp сервера для отправки писем
"port": 25, //порт smpt сервера для отправки писем
"from": "john.smith@gmail.com", //адрес отправителя
"to": [
"recepient1@gmail.com", //массив получателей
"recepient2@gmail.com"
]
}
}
Декларации для сборки библиотеки
CLI интерфейс
Просмотр данных реестра библиотек в хранилище
Выполняется командой node bin/ds view
с указанием дополнительных опций:
-r
или--repo
- название репозитория (необязательный параметр)-v
или--version
- название версии (тега или ветки) библиотеки (необязательный параметр)-s
или--storage
- название конфигурации хранилища для выполнения данной команды. Допустимые значенияtesting
иproduction
. Значение по умолчанию:testing
.
В случае если указаны оба параметра, то выведется информация по конкретной указанной версии библиотеки.
Если была передана только опция с названием библиотеки, то будет выведен список версий выбранной библиотеки.
Если не был передан ни один из параметров, то будет выведен список библиотек, которые находятся в настоящее время в реестре.
Удаление версии библиотеки из репозитория с собранными данными
Выполняется командой node bin/ds remove
с указанием дополнительных опций:
-r
или--repo
- название репозитория (обязательный параметр)-v
или--version
- название версии (тега или ветки) библиотеки (обязательный параметр)-d
или--dry
- режим тестового запуска. При этом данные не будут удалены а в консоль будет выведено соответствующее сообщение.-s
или--storage
- название конфигурации хранилища для выполнения данной команды. Допустимые значенияtesting
иproduction
. Значение по умолчанию:testing
.
ВНИМАНИЕ! При выполнении этой команды происходит НОБРАТИМОЕ УДАЛЕНИЕ из хранилища! Будьте внимательными при ее использовании.
Замена документа в собранных данных библиотеки
Выполняется командой node bin/ds replace
с указанием дополнительных опций:
-r
или--repo
- название репозитория (обязательный параметр)-v
или--version
- название версии (тега или ветки) библиотеки (обязательный параметр)-d
или--doc
- ключ документа в сборки библиотеки ('readme', 'changelog', 'migration', ...) (обязательный параметр)-l
или--lang
- языковая версия заменяемого документа. Если этот параметр неуказан, то будут заменены все яызковые версии документа, указанного в параметре-d
.-u
или--url
- url для*.md
файла источника замены на github, например: 'https://github.com/bem-site/bem-data-source/blob/master/README.md'.-s
или--storage
- название конфигурации хранилища для выполнения данной команды. Допустимые значенияtesting
иproduction
. Значение по умолчанию:testing
.
Примечание: Если значением параметра -u
или --url
указать null, то документ индекс
которого передан в параметре -d
или --doc
будет удален из общего файла с документацией.
Миграция данных между хранилищами
Выполняется командой node bin/ds migrate
с указанием дополнительных опций:
-r
или--repo
- название репозитория (обязательный параметр)-v
или--version
- название версии (тега или ветки) библиотеки (обязательный параметр)-d
или--dry
- режим тестового запуска. При этом данные не будут удалены а в консоль будет выведено соответствующее сообщение.-docs-only
или--docs-only
- флаг при указании которого будет смигрирован только файл документации. Примеры блоков отправлены не будут.-f
или--from
- название хранилища откуда будут смигрированы данные. Допустимыми значениями данного параметра являютсяtesting
иproduction
. По умолчанию выставлено значениеtesting
.-t
или--to
- название хранилища куда будут смигрированы данные. Допустимыми значениями данного параметра являютсяtesting
иproduction
. По умолчанию выставлено значениеproduction
.
Ручная публикация собранных данных библиотеки на удаленный сервер
Находясь в директории целевой библиотеки блоков, после сборки примеров и документации
можно вызвать команду publish
которая упакует собранные данные документации в формат
необходимый для сайта, проведет архивацию всех примеров, отправит все данные по документации
и примерам библиотеки в хранилище и добавит версию данной библиотеки в реестр собранных данных.
Пример:
node {path to bem-data-source}/bin/ds publish [-v version] [--docs-only] [-examples EXAMPLES] [-d]
-v
или--version
- необязательный параметр названия версии (ветка, тег, пулл-реквест). Если этот параметр не будет указан, то название версии будет выбрано из файлаpackage.json
.-docs-only
или--docs-only
- флаг при указании которого в удаленное хранилище будет отправлен только файл документации. Примеры блоков отправлены не будут.-examples
или--examples={pattern}
параметр позволяющий произвести отправку только тех примеров, путь к которым содержит значение переданного параметра. Например, если в библиотеке есть блокbutton
у которого есть примеры, то при вызове командыpublish -e button
, будут отправлены только файлы примеров относящиеся к этому блоку.-d
или--dry
- режим тестового запуска. При этом данные не будут отправлены в удаленное хранилище, а в консоль будет выведено соответствующее сообщение.-s
или--storage
- название конфигурации хранилища для выполнения данной команды. Допустимые значенияtesting
иproduction
. Значение по умолчанию:testing
.
Просмотр текущей версии приложения.
Посмотреть текущую версию приложения можно выполнив команду: node bin/ds -v
Работа c bem-data-source в режиме npm зависимости через API
API
Команды bem-data-source
можно выполнять не только вручную из коммандной строки, но также
с помощью сторонних модулей. Это дает возможность интеграции bem-data-source
в различные системы сборки документации и примеров библиотек блоков.
View:
Просмотр реестра собранных данных по библиотекам блоков.
var ds = require('bem-data-source');
ds.view(repo, version, options);
repo
- необязательный параметр названия библиотеки (ветка, тег, пулл-реквест)version
- необязательный параметр названия версии (ветка, тег, пулл-реквест)options
- опциональне настройки команды.
Возможные варианты применения:
Просмотр списка библиотек в реестре:
ds.view(null, null, options).then(function(libs) {
console.log(libs);
});
Просмотр списка версий библиотеки:
ds.view('bem-core', null, options).then(function(versions) {
console.log(versions);
});
Просмотр информации по отдельной версии библиотеки:
ds.view('bem-core', 'v2.3.0', options).then(function(version) {
console.log(version.sha);
console.log(version.date);
});
Remove:
Удаление собранных данных версии библиотеки.
var ds = require('bem-data-source');
ds.remove(repo, version, options, dryMode);
repo
- обязательный параметр названия библиотеки (ветка, тег, пулл-реквест)version
- обязательный параметр названия версии (ветка, тег, пулл-реквест)options
- опциональные настройки команды.dryMode
- Тестовое выполнение команды. При включенном флагеdryMode
в значенииtrue
, реального удаления данных не произойдет.
Replace:
Замена существующего документа (readme, documentation ...).
var ds = require('bem-data-source');
ds.replace(repo, version, options);
repo
- обязательный параметр названия библиотеки (ветка, тег, пулл-реквест)version
- обязательный параметр названия версии (ветка, тег, пулл-реквест)options
- дополнительные настройки команды. Объект с полями:
doc
- название документа. Допустимые значения: ('readme', 'changelog', 'migration', 'notes') (Обязательное поле)lang
- язык документа. Если данный параметр отсутствует, то будут заменены все версии документа для списка языков указанных в конфигурационном файле.url
- ссылка на*.md
документ который должен заменить существующий. По своей сути - это такая ссылка на документ на github которую можно увидеть в браузере при открытии этого файла на github. Например, для README.md bem-data-source:https://github.com/bem/bem-data-source/blob/master/README.md
Publish:
Публикация собраных данных.
var ds = require('bem-data-source');
ds.publish(version, options, dryMode);
version
- обязательный параметр названия версии (ветка, тег, пулл-реквест)options
- опциональне настройки команды.dryMode
- Тестовое выполнение команды. При включенном флагеdryMode
в значенииtrue
, реальной публикации данных не произойдет.
ВНИМАНИЕ: при выполнении данной команды process.cwd()
должен указывать на корневую директорию библиотеки.
Prepare:
Подготовка данных для отправки.
var ds = require('bem-data-source');
ds.prepare(version, options, dryMode);
version
- обязательный параметр названия версии (ветка, тег, пулл-реквест)options
- опциональне настройки команды.dryMode
- Тестовое выполнение команды.
Send:
Отправка данных в удаленное хранилище.
var ds = require('bem-data-source');
ds.send(version, options, dryMode);
version
- обязательный параметр названия версии (ветка, тег, пулл-реквест)options
- опциональне настройки команды.dryMode
- Тестовое выполнение команды.
Примечание: Результат последовательного вызова методов prepare
и send
эквивалентен вызову метода publish
.
Опциональные настройки для команд:
Помимо специфичных настроек (как например для метода replace), все методы API принимают объект с общими настройками. Они включают в себя такие поля:
storage
- объект с конфигурацией для хранилища.
storage: {
namespace: 'my-site', //пространство имен для ключей данных
get: {
host: '127.0.0.1', //хост для запросов на чтение данных
port: 3000 //порт для запросов на чтение данных
},
post: {
host: '127.0.0.1', //хост для запросов на изменение данных
port: 3001 //порт для запросов на изменение данных
},
auth: '' - заголовок с параметрами авторизации. Нужен для запросов на изменение данных
}
mailer
- объект с настройками почтовой рассылки.
{
"mailer": {
"host": "your e-mail-host", //хост smtp сервера для отправки писем
"port": 25, //порт smpt сервера для отправки писем
"from": "john.smith@gmail.com", //адрес отправителя
"to": [
"recepient1@gmail.com", //массив получателей
"recepient2@gmail.com"
]
}
}
logger
- настройки инструмента логгирования. Объект содержащий полеlevel
(по умолчанию 'info')maxOpenFiles
- максимальное число одновременно открытых файлов (по умолчанию 100)
Примечание:
Для команд send
и publish
доступна также опция isDocsOnly
. Это булевый флаг.
Если при выполнении этих команд данная опция будет иметь значение true
, то в хранилище будет выполнена
только отправка файла с документацией библиотеки. Отправка файлов примеров выполнена не будет.
Тестирование
Запуск тестов:
npm run mocha
Запуск тестов с покрытием:
npm run istanbul
Запуск проверки codestyle (jshint и jscs)
npm run codestyle
Особая благодарность за помощь в разработке:
- Ильченко Николай (http://github.com/tavriaforever)
- Константинова Гела (http://github.com/gela-d)
Ответственный за разработку @bemer Вопросы и пожелания присылать по адресу: bemer@yandex-team.ru