bem-data-source

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

bem-data-source может быть использован в двух различных режимах работы:

1. Как самостоятельная nodejs cli утилита
2. Как 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": "[email protected]", //адрес отправителя
     "to": [
       "[email protected]", //массив получателей
       "[email protected]"
     ]
  }
}

Декларации для сборки библиотеки

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": "[email protected]", //адрес отправителя
     "to": [
       "[email protected]", //массив получателей
       "[email protected]"
     ]
  }
}

• 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 Вопросы и пожелания присылать по адресу: [email protected]