bem-data-source

    1.11.0 • Public • Published

    bem-data-source

    NPM

    Coveralls branch Travis David David

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

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

    Keywords

    none

    Install

    npm i bem-data-source

    DownloadsWeekly Downloads

    2

    Version

    1.11.0

    License

    MPL-2.0

    Unpacked Size

    138 kB

    Total Files

    63

    Last publish

    Collaborators

    • dexig
    • gela-d
    • tadatuta
    • tavriaforever
    • tormozz48