Привет!

Пока почитать, к сожалению, негде — документация в процессе написания.

Минимальный кейс использования предполагается такой:

1. Поставить bem-lib-site
2. Создать конфиг .bemrc, в котором описать собираемую библиотеку (пример).
3. Вызвать бинарник bem-lib-site с указанием пути к собираемой библиотеке: bem-lib-site bem-core

Если ничего в процессе не взорвалось, то на выходе в папке, указанной в конфиге как outputFolder появится куча файлов, среди которых будут папки для каждого собираемого языка и в них папки с документацией по каждому блоку. Это дело должно быть можно открывать хоть с файловой системы, хоть паблишить на gh-pages.

Если что-то идет не так (а такое вполне возможно на данном этапе) — заводи 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 или я неправильно понял? Про .bemrc тоже еще ничего почитать?

Про .bemrc см. https://github.com/bem-sdk/bem-config и, если нужны подробности, https://github.com/tadatuta/betterc

На баг посмотрю, отпишусь, если что-то выясню.

@ilyar а что лежит в этот момент в docstest? если там пусто, то ничего сгенерироваться и не может. папка, на которую натравливается bem-lib-site обязана быть «полноценной» библиотекой блоков (у нее должен быть package.json с указанием имени и в конфиге .bemrc должно что-то про эту библиотеку.

@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

Что дорожно быть в templateEngine?

На самом деле libConfig должен быть объектом, а если templateEngine не окажется, то там сработает фоллбек. Оно сейчас падает, т.к. не намайнился конфиг для либы.

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

Кроме того я начал пилить тесты, так что будет что использовать в качестве примера.

Работает, если в конфиг добавить:

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

@tadatuta

При повторном запуске bem-lib-site . получаю ошибку:

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 .

Да, уже влили (см. https://github.com/bem-site/bem-lib-site-data/pull/10), но еще нет версии с правками.

@tadatuta для ошибки: "TypeError: Cannot read property 'templateEngine' of undefined" уже есть решение https://github.com/bem-site/bem-lib-site-data/commit/af09ab03060d739e9bf3abe9fcaf6d238aabcd9d надо только выпустить новую версию 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 из корня библиотеки, но сейчас это не реализовано.

Понял, спасибо.

Выражу личное мнение, думаю, будет удобно следующие поведение:

• язык документации по умолчанию (когда в конфиге отсутствует langs) , данные для него будут браться из файла технологии без суффикса т.е. project/blocks/b1/b1.md и project/readme.md;
• readme.md из корня библиотеки должен быть регистронезависимый;
• индекс документации это список блоков дополненный информацией из корневого readme.md это может быть опциональным поведением.

Еще уточнение по использованию, каким образом на данный момент можно вмешаться в формирование конечного результата? Хочу добавить индекс.

Я в процессе фикса индекса, changelog и migration для библиотеки

@ilyar можно заводить issues в соответствующих репозиториях и после обсуждения брать в работу, если есть желание/возможность. буду очень благодарен!

https://github.com/bem-site/bem-lib-site-data/issues/13 https://github.com/bem-site/bem-lib-site-data/issues/14 https://github.com/bem-site/bem-lib-site-view/issues/11

Повторил все шаги выше. Но выдается ошибка Cannot read property 'outputFolder' of undefined at Object. (/usr/local/lib/node_modules/bem-lib-site/node_modules/bem-lib-site-view/lib/process-blocks.js:14:26).

.bemrc в корне проекта лежит, все ок. Может изменился способ задания конфига?

Очень уж хочется попробовать, но за два подхода тулза не взлетела...

@kompolom @kmadorin

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 Попробовал снова собрать доки. Все сломалось!

Data was collected at /home/jenik/myprojects/bem-lib-site-test/docs/data/.-
module.js:327
    throw err;
    ^

Error: Cannot find module '/home/jenik/myprojects/bem-lib-site-test/docs/data/data'

@kompolom, у меня тоже сборка развалилась после обновления на bem-core#v4. Сегодня @tadatuta в Телеграмме говорил, что там пока много «ненадёжностей» и грозился в ближайшее время (сегодня) «влить туда пачку фиксов и в перспективе планируют переводить на v4».

Посмотрите внимательно на .bemrc, там изменился формат.

Сейчас так:

module.exports = {
    root: true,

    modules: {
        'bem-lib-site': {
            langs: ['uk', 'ru', 'en'],

            data: {
                tempFolder: 'tmp',
                outputFolder: '.cache/bem-lib-site-data'
            },
            view: {
                outputFolder: 'bem-lib-site-view-output'
            },
            platforms: { // TODO: make it really optional
                'desktop': ['common', 'deskpad', 'desktop', 'test'],
                'touch-phone': ['common', 'touch', 'touch-phone', 'test'],
                'touch-pad': ['common', 'deskpad', 'touch', 'touch-pad', 'test']
            },
            libs: {
                'bem-components': {
                    langs: ['uk', 'ru', 'en'],
                    github: {
                        url: 'github.com',
                        user: 'bem',
                        repo: 'bem-components',
                        defaultBranch: 'v3.0.0'
                    }
                }
            }
        }
    }
};

Может в этом дело.

Была бы хоть какая то документация что в конфиге писать куда и зачем...

@vithar Вот сгенерировал я данные в папку cache/bem-lib-site-data запускаю bem-lib-site-view cache и получаю:

module.js:327
    throw err;
    ^

Error: Cannot find module '/home/jenik/myprojects/ap-components/cache/data'
    at Function.Module._resolveFilename (module.js:325:15)
    at Function.Module._load (module.js:276:25)
    at Module.require (module.js:353:17)
    at require (internal/module.js:12:17)
    at module.exports (/home/jenik/myprojects/ap-components/node_modules/bem-lib-site-view/lib/prepare-data.js:27:19)
    at module.exports (/home/jenik/myprojects/ap-components/node_modules/bem-lib-site-view/index.js:21:16)
    at Object.<anonymous> (/home/jenik/myprojects/ap-components/node_modules/bem-lib-site-view/bin/bem-lib-site-view:3:14)
    at Module._compile (module.js:409:26)
    at Object.Module._extensions..js (module.js:416:10)
    at Module.load (module.js:343:32)

Никак не пойму что за модуль оно там найти хочет. Вот что нагенерил bem-site-data:

20:29 jenik@baranov-pc:~/myprojects/ap-components$ tree -L 4 cache/
cache/
└── bem-lib-site-data
    └── ap-components-1.1.0
        ├── bower.json
        ├── data.json
        ├── desktop.docs
        │   ├── accordion
        │   ├── alert
        │   ├── animate
        │   ├── attach
        .... // тут еще куча папок соотв блокам
        │   ├── widget
        │   └── widget-area
        └── readme.md

52 directories, 3 files

Ну ладно, может вложенность увеличилась, пробую запускать указываю путь до библиотеки, ошибка поменялась:

 bem-lib-site-view cache/bem-lib-site-data/ap-components-1.1.0/
[TypeError: Path must be a string. Received undefined]

Оно ищет data.json.

Так должно работать: bem-lib-site-view cache/bem-lib-site-data/ap-components-1.1.0