bem-data-source
Advanced tools
Readme
Данный инструмент предназначен для публикации данных документации и примеров по библиотекам блоков.
bem-data-source может быть использован в двух различных режимах работы:
git clone git://github.com/bem/bem-data-source.gitcd bem-data-sourcenpm installnpm run config.
(После выполнения npm run config должен появиться новый конфигурационный файл config/private.json).Конфигурация инструмента описывается в файлах config/public.json, config/private.json.
logLevel - флаг уровня логгирования. может принимать значения: ("verbose", "debug", "info", "warn", "error")languages - массив локалейmaxOpenFiles - максимальное количество открытых файлов. Этот параметр также определяет размер
порций файлов которые одновременно записываются в хранилище.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"
]
}
}
Выполняется командой 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
Команды bem-data-source можно выполнять не только вручную из коммандной строки, но также
с помощью сторонних модулей. Это дает возможность интеграции bem-data-source
в различные системы сборки документации и примеров библиотек блоков.
Просмотр реестра собранных данных по библиотекам блоков.
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);
});
Удаление собранных данных версии библиотеки.
var ds = require('bem-data-source');
ds.remove(repo, version, options, dryMode);
repo - обязательный параметр названия библиотеки (ветка, тег, пулл-реквест)version - обязательный параметр названия версии (ветка, тег, пулл-реквест)options - опциональные настройки команды.dryMode - Тестовое выполнение команды. При включенном флаге dryMode в значении true,
реального удаления данных не произойдет.Замена существующего документа (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Публикация собраных данных.
var ds = require('bem-data-source');
ds.publish(version, options, dryMode);
version - обязательный параметр названия версии (ветка, тег, пулл-реквест)options - опциональне настройки команды.dryMode - Тестовое выполнение команды. При включенном флаге dryMode в значении true,
реальной публикации данных не произойдет.ВНИМАНИЕ: при выполнении данной команды process.cwd() должен указывать на корневую директорию библиотеки.
Подготовка данных для отправки.
var ds = require('bem-data-source');
ds.prepare(version, options, dryMode);
version - обязательный параметр названия версии (ветка, тег, пулл-реквест)options - опциональне настройки команды.dryMode - Тестовое выполнение команды.Отправка данных в удаленное хранилище.
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
Особая благодарность за помощь в разработке:
Ответственный за разработку @bemer Вопросы и пожелания присылать по адресу: bemer@yandex-team.ru
FAQs
bem-data-source ===============
The npm package bem-data-source receives a total of 37 weekly downloads. As such, bem-data-source popularity was classified as not popular.
We found that bem-data-source demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.