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": "[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]

Name		Name	Last commit message	Last commit date
Latest commit History 786 Commits
.githooks/pre-commit		.githooks/pre-commit
bin		bin
config		config
declarations		declarations
docs		docs
drafts		drafts
src		src
test		test
.borschik		.borschik
.coveralls.yml		.coveralls.yml
.gitignore		.gitignore
.istanbul.yml		.istanbul.yml
.jscs.js		.jscs.js
.jshintignore		.jshintignore
.jshintrc		.jshintrc
.npmignore		.npmignore
.travis.yml		.travis.yml
CONTRIBUTORS.md		CONTRIBUTORS.md
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

bem-data-source

Работа c bem-data-source в режиме консольной утилиты

Установка

Конфигурирование

Файл config/public.json

Файл config/private.json

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

CLI интерфейс

Просмотр данных реестра библиотек в хранилище

Удаление версии библиотеки из репозитория с собранными данными

Замена документа в собранных данных библиотеки

Миграция данных между хранилищами

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

Просмотр текущей версии приложения.

Работа c bem-data-source в режиме npm зависимости через API

API

View:

Просмотр списка библиотек в реестре:

Просмотр списка версий библиотеки:

Просмотр информации по отдельной версии библиотеки:

Remove:

Replace:

Publish:

Prepare:

Send:

Опциональные настройки для команд:

Тестирование

About

Releases 3

Packages

Contributors 6

Languages

License

bem-site/bem-data-source

Folders and files

Latest commit

History

Repository files navigation

bem-data-source

Работа c bem-data-source в режиме консольной утилиты

Установка

Конфигурирование

Файл config/public.json

Файл config/private.json

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

CLI интерфейс

Просмотр данных реестра библиотек в хранилище

Удаление версии библиотеки из репозитория с собранными данными

Замена документа в собранных данных библиотеки

Миграция данных между хранилищами

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

Просмотр текущей версии приложения.

Работа c bem-data-source в режиме npm зависимости через API

API

View:

Просмотр списка библиотек в реестре:

Просмотр списка версий библиотеки:

Просмотр информации по отдельной версии библиотеки:

Remove:

Replace:

Publish:

Prepare:

Send:

Опциональные настройки для команд:

Тестирование

About

Resources

License

Stars

Watchers

Forks

Releases 3

Packages 0

Contributors 6

Languages

Packages