Bem-data-source

Tool for collect documentation and exaples from libraries and common sources for bem-info and legoa

Project maintained by bem-site Hosted on GitHub Pages — Theme by mattgraham

bem-data-source

Build Status Dependency Status devDependency Status

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

Установка

После выполнения npm run config должен появиться новый конфигурационный файл config/private.json.

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

Конфигурация инструмента описывается в файлах config/public.json, config/private.json.

Файл config/public.json

"storage": {
    "cocaine": {
        "debug": false
    }
}

Файл config/private.json

В этом файле настриваются приватные параметры приложения, например пространство имен для хранилища:

{
  "storage": {
    "cocaine": {
      "namespace": "your_application_namespace"
    }
  }
}

Настройки почтовой рассылки:

{
  "mailer": {
    "host": "your e-mail-host",
     "port": 25,
     "from": "john.smith@gmail.com",
     "to": [
       "recepient1@gmail.com",
       "recepient2@gmail.com"
     ]
  }
}

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

CLI интерфейс

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

Выполняется командой node bin/ds view с указанием дополнительных опций:

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

Если была передана только опция с названием библиотеки, то будет выведен список версий выбранной библиотеки.

Если не был передан ни один из параметров, то будет выведен список библиотек, которые находятся в настоящее время в реестре.

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

Выполняется командой node bin/ds remove с указанием дополнительных опций:

ВНИМАНИЕ! При выполнении этой команды происходит НОБРАТИМОЕ УДАЛЕНИЕ из хранилища! Будьте внимательными при ее использовании.

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

Выполняется командой node bin/ds replace с указанием дополнительных опций:

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

Находясь в директории целевой библиотеки блоков, после сборки примеров и документации можно вызвать команду publish которая упакует собранные данные документации в формат необходимый для сайта, проведет архивацию всех примеров, отправит все данные по документации и примерам библиотеки в хранилище и добавит версию данной библиотеки в реестр собранных данных.

Пример:

node {path to bem-data-source}/bin/ds publish [-v version]

Где -v - необязательный параметр названия версии (ветка, тег, пулл-реквест). Если этот параметр не будет указан, то название версии будет выбрано из файла package.json

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

Посмотреть текущую версию приложения можно выполнив команду: node bin/ds -v

API

Команды bem-data-source можно выполнять не только вручную из коммандной строки, но также с помощью сторонних модулей. Это дает возможность интеграции bem-data-source в различные системы сборки документации и примеров библиотек блоков.

View:

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

var ds = require('bem-data-source');
ds.view(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);

Replace:

Замена существующего документа (readme, documentation ...).

var ds = require('bem-data-source');
ds.replace(repo, version, options);

Publish:

Публикация собраных данных.

var ds = require('bem-data-source');
ds.publish(version, options, dryMode);

ВНИМАНИЕ: при выполнении данной команды process.cwd() должен указывать на корневую директорию библиотеки.

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

Помимо специфичных настроек (как например для метода replace), все методы API принимают объект с общими настройками. Они включают в себя такие поля:

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

Запуск тестов:

npm run mocha

Запуск тестов с покрытием:

npm run istanbul

Запуск проверки codestyle (jshint и jscs)

npm test

Ответственный за разработку @bemer

Вопросы и пожелания присылать по адресу: bemer@yandex-team.ru