search

bem-site / bem-forum-content-ru

Content BEM forum for Russian speak users
MIT License
56 stars 6 forks source link

enb-bem-docs как готовить jsdoc? #667

Open kompolom opened 9 years ago

kompolom commented 9 years ago

Захотелось собрать документацию к проекту. Поставил модуль из топика, добавил конфиг в make.js по аналогии с bem-components. Доки собрались. Но

Попробовал собрать доки в bem-components - то же самое. Подскажите, как собрать полную, красиво оформленную документацию к проекту, например, как на этом сайте.

tadatuta commented 9 years ago

вообще нет стилей

enb-bem-docs отвечает только за сборку данных, необходимых для построения сайта. Сам сайт генерируется с помощью bem-site-engine.

Есть jsdoc.html но он пустой всегда, хотя в блоках есть jsdoc комменты

enb-bem-docs в зависимости от опции jsdoc поддерживает либо jsd + bem-jsd + jsd-plugins-bem либо JSDoc3 + bem-jsdoc3-plugin.

Соответственно нужно выбрать один из форматов и ему следовать. Все прочие диалекты в лучшем случае будут работать частично.

PS: В планах есть разработка инструмента, который будет генерировать сайты библиотек гораздо удобнее, чем существующие решения, но текущий статус — закрытая альфа, сроков релиза пока нет. Но если твой проект в открытом доступе, я бы для эксперимента попробовал бы собрать для него сайт (результаты — это HTML-статика, готовая для публикации на gh-pages, так что если что-то внятное соберется, смогу отдать) — был бы дополнительный полигон для тестирования.

pavelpower commented 9 years ago

@tadatuta дело в том, что нет нормально описанного полноценного гайда как завести документы на своем проекте.

Я уже слишком много перелопатил, и до сих пор не могу нормально запустить сборку документации на проекте.

Исходные данные:

Желаемый результат:

tadatuta commented 9 years ago

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

kompolom commented 9 years ago

Было бы здорово. Потому что без нормальной доки все очень грустно. В какой то момент вдруг обнаруживается два-три разных блока которые выполняют одну и ту же задачу.

kompolom commented 8 years ago

@tadatuta Изменилось ли что то на текущий момент в генерировании документации? В идеале, хотелось бы запустить локально что то вроде раздела "библиотеки" с bem.info.