New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Как использовать bem-lib-site? #1083
Comments
Привет! Пока почитать, к сожалению, негде — документация в процессе написания. Минимальный кейс использования предполагается такой:
Если ничего в процессе не взорвалось, то на выходе в папке, указанной в конфиге как Если что-то идет не так (а такое вполне возможно на данном этапе) — заводи issues, буду чинить. |
npm i -g bem-lib-site
cd docstest
cat .bemrc module.exports = {
modules: {
'bem-tools': {
plugins: {}
},
'bem-lib-site-data': {
tempFolder: 'tmp',
outputFolder: 'output',
langs: ['ru', 'en'],
platforms: { // TODO: make it really optional
'desktop': ['common', 'deskpad', 'desktop'],
'touch-phone': ['common', 'touch', 'touch-phone'],
'touch-pad': ['common', 'deskpad', 'touch', 'touch-pad']
},
libs: {
'bem-components': {
langs: ['ru', 'en'],
github: {
url: 'github.com',
user: 'bem',
repo: 'bem-components',
defaultBranch: 'v3'
}
}
}
}
}
}; bem-lib-site .
TypeError: Cannot read property 'libs' of undefined
at Object.<anonymous> (/home/ilyar/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/bem-lib-site-data/.enb/make.js:15:21)
at Module._compile (module.js:413:34)
at Object.Module._extensions..js (module.js:422:10)
at Module.load (module.js:357:32)
at Function.Module._load (module.js:314:12)
at Module.require (module.js:367:17)
at require (internal/module.js:16:19)
at module.exports.inherit.init (/home/ilyar/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/enb/lib/make.js:90:17)
at module.exports (/home/ilyar/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/enb-magic-platform/lib/apply.js:25:25)
at Object.module.exports [as runTasks] (/home/ilyar/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/enb-magic-platform/lib/api/run-tasks.js:28:12) Заводить issues или я неправильно понял? |
Про На баг посмотрю, отпишусь, если что-то выясню. |
@ilyar а что лежит в этот момент в |
@tadatuta Папка действительно пуста это воспроизводится по сценарию из bem-lib-site#1. Осознав что папка должна быть полноценной получается такой кейс: # 1. инструмент
npm i -g bem-lib-site
# 2. среда
rm -fr docstest && mkdir docstest && cd $_
# 3. проект
npm init -f
# 4. конфигурация
echo "module.exports = {
'root': true,
'levels': {
'blocks': {
'scheme': 'nested',
'default': true
}
},
modules: {
'bem-tools': {
plugins: {}
},
'bem-lib-site-data': {
tempFolder: 'tmp',
outputFolder: 'distr/docs',
langs: ['ru', 'en'],
}
}
};" | tee .bemrc
# 5. папки
mkdir -p blocks/b1 distr/docs
# 6. файлы
echo "# Block b1" | tee blocks/b1/b1.{en,ru}.md
echo ".b1 {}" | tee blocks/b1/b1.css
# 7. проверяем
tree
.
├── blocks
│ └── b1
│ ├── b1.css
│ ├── b1.en.md
│ └── b1.ru.md
├── distr
│ └── docs
│ └── data
└── package.json
5 directories, 4 files
# 8. генерация документации
bem-lib-site .
/home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/bem-lib-site-data/index.js:36
process.env.BEM_TEMPLATE_ENGINE = libConfig.templateEngine || config.templateEngine;
^
TypeError: Cannot read property 'templateEngine' of undefined
at module.exports (/home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/bem-lib-site-data/index.js:36:48)
at module.exports (/home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/index.js:10:12)
at Object.<anonymous> (/home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/bin/bem-lib-site:3:14)
at Module._compile (module.js:413:34)
at Object.Module._extensions..js (module.js:422:10)
at Module.load (module.js:357:32)
at Function.Module._load (module.js:314:12)
at Function.Module.runMain (module.js:447:10)
at startup (node.js:139:18)
at node.js:999:3 Что дорожно быть в |
На самом деле Но в такой постановке проблема понятна, я добавлю еще фоллбеков, чтобы оно могло либо что-то осмысленное в консоль писать, либо даже какой-то полезный результат генерить. Кроме того я начал пилить тесты, так что будет что использовать в качестве примера. |
Работает, если в конфиг добавить: libs: {
docstest: {},
} в итоге: # 4. конфигурация
echo "module.exports = {
'root': true,
'levels': {
'blocks': {
'scheme': 'nested',
'default': true
}
},
modules: {
'bem-lib-site-data': {
outputFolder: 'distr/docs',
langs: ['ru', 'en'],
libs: {
docstest: {},
},
}
}
};" | tee .bemrc |
При повторном запуске Error: Cannot delete files/folders outside the current working directory. Can be overriden with the `force` option.
at safeCheck (/home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/del/index.js:19:9)
at /home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/del/index.js:35:5
at Array.map (native)
at /home/user/.nvm/versions/node/v5.5.0/lib/node_modules/bem-lib-site/node_modules/del/index.js:33:28 Вероятно надо https://github.com/bem-site/bem-lib-site-view/pull/8/files Обходное решение: # 8. генерация документации
rm -rf distr/docs/** && bem-lib-site . |
Да, уже влили (см. bem-site/bem-lib-site-data#10), но еще нет версии с правками. |
@tadatuta для ошибки: "TypeError: Cannot read property 'templateEngine' of undefined" уже есть решение bem-site/bem-lib-site-data@af09ab0 надо только выпустить новую версию bem-lib-site-data и bem-lib-site https://github.com/bem-site/bem-lib-site/blob/master/package.json#L19 |
я хочу еще несколько фиксов сделать до выпуска |
Ясно, спасибо. Есть еще один не понятный моменте, bem-lib-site генерирует следующие: tree distr/docs/
distr/docs/
├── data
│ └── docstest
│ ├── bower.json
│ ├── data.json
│ └── desktop.docs
│ └── b1
│ ├── b1.bemdecl.js
│ ├── b1.data.json
│ ├── b1.en.doc.html
│ ├── b1.en.md
│ ├── b1.jsdoc.html
│ ├── b1.jsdoc.json
│ ├── b1.jsdoc.md
│ ├── b1.meta.json
│ ├── b1.ru.doc.html
│ ├── b1.ru.md
│ └── b1.source-files.json
└── docstest
├── en
│ ├── desktop
│ │ └── b1
│ │ └── index.html
│ ├── index.css
│ └── index.js
└── ru
├── desktop
│ └── b1
│ └── index.html
├── index.css
└── index.js
11 directories, 19 files Другими словами получаем страничку документации по каждому блоку. @tadatuta Не хватает индекса, bem-lib-site это умеет или надо что-то придумывать? Пожалуйста подскажи, как это можно сделать. |
По задумке индексом должен быть отрендеренный README[.lang].md из корня библиотеки, но сейчас это не реализовано. |
Понял, спасибо. Выражу личное мнение, думаю, будет удобно следующие поведение:
Еще уточнение по использованию, каким образом на данный момент можно вмешаться в формирование конечного результата? Хочу добавить индекс. |
Я в процессе фикса индекса, changelog и migration для библиотеки |
@ilyar можно заводить issues в соответствующих репозиториях и после обсуждения брать в работу, если есть желание/возможность. буду очень благодарен! |
Повторил все шаги выше. Но выдается ошибка Cannot read property 'outputFolder' of undefined .bemrc в корне проекта лежит, все ок. Может изменился способ задания конфига? |
Очень уж хочется попробовать, но за два подхода тулза не взлетела... |
git clone git@github.com:ilyar/bem-lib-site-test.git
cd bem-lib-site-test && npm install
npm test
open docs/index.html Работает, хак внутри (может быть он уже не нужен). |
Сборку можно посмотреть тут ilyar.github.io/bem-lib-site-test/. |
@ilyar, Спасибо за демку, завелось наконец-то! У меня только jsdoc собрался. md файлы не подключились. |
@ilyar Попробовал снова собрать доки. Все сломалось! |
|
Посмотрите внимательно на .bemrc, там изменился формат. Сейчас так:
|
Может в этом дело. |
Была бы хоть какая то документация что в конфиге писать куда и зачем... |
@vithar Вот сгенерировал я данные в папку
Никак не пойму что за модуль оно там найти хочет.
Ну ладно, может вложенность увеличилась, пробую запускать указываю путь до библиотеки, ошибка поменялась:
|
Оно ищет data.json. Так должно работать: |
@kompolom @Realetive @vithar во всем виноват этот коммит bem-site/bem-lib-site-data@1c7f630 |
@ilyar Виноват, но не во всем
|
Согласен, поторопился с выводами, проблема фиксится так: ilyar/bem-lib-site-test@c77da0d Обновленное демо https://ilyar.github.io/bem-lib-site-test/ и о счастье маркдаун теперь рендерится! @vithar спасибо за обновление. |
Все таки пришлось откатить bem-site/bem-lib-site-data до 7f13647f теперь на мастере валится https://travis-ci.org/ilyar/bem-lib-site-test/jobs/183339355#L1298 Пока оставлю так. |
Ребята, спасибо, что вы все это терпите. |
Ждем с нетерпением |
Добрался до попыток привинчивания bem-lib-site. Третий день экспериментов с практически нулевым результатом. Использовал в качестве отправной точки bem-lib-site-test. Получается, что без изменений либо кода пакетов ( Старался обходиться минимальными правками и только в конфиге (хотя по началу делал всякие допроверки вроде Прошу помочь с настройкой или ткнуть в рабочий кейс или правильный образец Сейчас out/data/index.css
out/data/index.js При этом в папке b1.bemdecl.js
b1.data.json
b1.en.md
b1.en.doc.html
b1.jsdoc.html
b1.jsdoc.json
b1.jsdoc.md
b1.meta.json
b1.ru.md
b1.ru.doc.html -- в котором все Также создаётся файл Конфиг сейчас (в последних экспериментах) такой: module.exports = {
root : true,
levels : {
'blocks' : {
scheme : 'nested',
default : true,
},
},
modules : {
'bem-lib-site-data' : {
tempFolder : 'out/temp',
outputFolder : 'out/data',
libs : {
'.' : {
templateEngine : 'BEMHTML',
},
},
},
},
}; Вывод команды
Тестируется на Windows7, node@v6.10.0. bem-lib-site установлен глобально:
|
Сумбурно как то, давай по порядку, что из этого сценария не работает?
|
@ilyar Это работает, спасибо. Раньше пробовал в основном через bem-lib-site. Это, видимо, какая-то проблема с установкой bem-lib-site-view в автоматическом режиме? Попробую плясать от этой конфигурации. Чуть вопросов:
|
|
@tadatuta какие есть обновления по инструменту (где почитать)? |
Подскажите, изменилась ли ситуаиция за прошедшее время? Или так же надо использовать бубны для запуска докогенератора? Собственные эксперименты лежат до сих в наполовину рабочем виде, к рабочим проектам подключать так пока руки не дошли. Сейчас начинать с них? Или можно попробовать какой-то более гуманный способ? (Наск. помню, были ещё доп. сложности из-за моего не оч. стандартного способа хранения блоков в проекте...) |
Привет. Я не знаю судьбу bem-lib-site-data, но мы сейчас пробуем с другой стороны зайти к снаряду в https://github.com/agrarium/agrarium Это прототип, но нам нравится как идут дела. Пока не нравится, что нет толковых парсеров для кода и jsdoc, и много руками надо будет писать) Но это лирика. |
@tadatuta рассказал как использовать автоматическую генерацию актуальной документации для модульного фронтенда, презентация.
Осталось не понятно, как это использовать. Покажите минимальный кейс использования bem-lib-site и расскажите где читать про остальное.UPD
Работает, хак внутри (может быть он уже не нужен).
Сборку можно посмотреть тут ilyar.github.io/bem-lib-site-test/.
UPD 1/1/17
Убрал один хак ilyar/bem-lib-site-test@a18e484, добавил автотест генерации доки:
The text was updated successfully, but these errors were encountered: