Skip to content

Latest commit

 

History

History
164 lines (131 loc) · 8.08 KB

declarations.md

File metadata and controls

164 lines (131 loc) · 8.08 KB
Raw

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

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

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

Для этого в папке 'declaration' необходимо создать js файл, название которого совпадает с названием библиотеки которую необходимо собрать, например bem-components.js.

Простейшая структура такого файла должна иметь вид:

module.exports = {
    default: {}
};

Для библиотеки bem-components:

module.exports = {
    default: {
        builder: 'enb',
        docDirs: '*.docs',
        rsync: {
            levels: ['desktop', 'touch'],
            targets: ['*.examples', '*.pages'],
            exclude: ['*.bemdecl.js', '*.browser.bemhtml.js', '*.browser.js',
                '*.deps.js', '*.js-js.bemdecl.js', '*.js.bemdecl.js', '*.js.deps.js', '*.pre.js',
                '*.template.bemdecl.js', '*.template.deps.js']
        },
        showcase: {
            title: 'showcase',
            path: 'desktop.pages/showcase/showcase.html'
        },
        docs: {
            readme: {
                folder: '',
                pattern: {
                    en: 'README.md',
                    ru: 'README.ru.md'
                }
            },
            changelog: {
                folder: '',
                pattern: 'CHANGELOG.md'
            },
            migration: {
                folder: '',
                pattern: 'MIGRATION.md'
            }
        },
        pattern: {
            data: '%s.data.json',
            jsdoc: '%s.jsdoc.html'
        }
    }
};

Здесь:

builder

Название инструмента с помощью которого будет выполняться сборка документации и примеров.

Допустимые значения enb и bem-tools. Значение по умолчанию bem-tools.

###docDirs Шаблон директорий которые содержат файлы с документацией по блокам.

rsync

Объект с допустимыми полями levels, targets, include, exclude.

  • levels - массив с именами уровней переопределения (без суффиксов).

DEPRECATED.

Данный параметр не используется. Выбираются все папки имена которых удовлетворяют условиям параметра targets, после чего происходит проверка действительного существования этих директорий на файловой системе. В качестве доступных имен уровней переопределения используется массив: ['desktop', 'touch', 'touch-pad', 'touch-phone']

  • targets - массив паттернов для папок примеров и прощих папок, которые должны быть идентифицированы как результат сборки. Директории попадающие под этот паттерн будуь скопированы в выходную директорию и в конечном итоге попадут в github репозиторий.

  • include - маски имен файлов которые будут включены в процесс копирования и обработки.

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

В массив exclude следует помещать паттерны тех файлов примеров которые должны быть исключены из итогового набора. Например, из итогового набора файлов примеров нужно исключить декларации блоков (файлы *.bemdecl.js). Тогда в массив exclude следует добавить соответствующий паттерн '*.bemdecl.js'.

Иногда возникает такая ситуация, когда часть файлов подпадающих под фильтр exclude, тем не менее должна быть вовлечена в процесс копирования и присутствовать в итоговом наборе файлов примеров. В этом случае паттерны таких файлов, должны быть добавлены в массив include.

Например, нужно исключить все *.css файлы, но при этом оставить все css файлы, названия которых начинаются со знака подчеркивания. Массивы exclude и include в этом случае будут иметь вид:

exclude: [*.css],
include: ['_*.css', '_*.ie.css', '_*.ie6.css', '_*.ie7.css', '_*.ie8.css', '_*.ie9.css']

Более подробно о значении параметров include и exclude можно почитать например:

showcase

Для некоторых библиотек необходимо отображать страницу с примерами всех блоков, так называемый showcase. Для этого в декларации указывается объект showcase, с полями:

  • title - название страницы
  • path - путь к с html файлу сгенерированной страницы showcase

docs

Объект с полями, которые в свою очередь также являются объектами. Позволяет задавать произвольный набор документов которые должны попасть в сборку библиотеки

docs: {
    readme: {
        folder: '',
        pattern: 'README.md'
    },
    changelog: {
        folder: 'docs',
        pattern: {
            en: 'CHANGELOG.en.md',
            ru: 'CHANGELOG.en.md'
        }
    },
    migration: {
        pattern: 'https://github.com/bem/bem-core/tree/v2/MIGRATION.md'
    }
    ...
}

Здесь 'README.md' - загружается из корня проекта. Файлы changelog-ов будут загружены из директории 'docs', по маске 'CHANGELOG.en.md' и 'CHANGELOG.ru.md' соответственно. При этом будут выбраны последние версии таких файлов, в случае когда в данной директории хранится несколько changelog - файлов и их названия содержат номер версии библиотеки. Файл миграции напрямую загружается с гитхаба с помощью github API с указанного адреса.

Из данного примера видно, что можно задавать разные файлы для различных языков, а также указывать произвольный url к файлу как адрес данного файла в браузере.

pattern

Объект с полями data и jsdoc в котором можно указать шаблоны файлов с документацией и js документацией к блокам.

Значение по умолчанию:

pattern: {
    data: '%s.data.json',
    jsdoc: '%s.jsdoc.json'
}