Кто-то собирается посетить?

Всем привет!

Мои генерят на yard. Не знаю, насколько это правильно и удобно. Используют и все

Ruby code documentation.

Друзья-рубисты, а расскажите, как вы документируете код? Чем лучше сгенерить красивый и удобный сайт с документацией по коду? А ещё,  как писать комментарии к методам, чтобы среда разработки их понимала и показывала? У меня IDEA c плагином Ruby, но могу поставить RubyMine.

Задача такая: есть немного кода на Ruby, я его сейчас понял, а через месяц снова забуду. Хочу грамотно написать комментарии в коде (это план-минимум) и сгенерить сайтик с документацией (это план-максимум).

Похоже, что официальная документация сделана на RDoc, но она какая-то несимпатичная, простите уж. Ещё есть YARD, и ruby-doc.org хорошо выглядит, но неясно, чем сгенерили.

В общем, расскажите, что самое лучшее, правильное и удобное? Приходите в @docsascode или в личку @nick_volynkin.

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

Был в прошлом году, хочу ещё

завидую )

А сколько стоит участие?

Вдруг интересно - Влад Балин подобрал несколько инструментов для генерации статических сайтов:

#geeky #staticsites #generators #react

В прошлый раз я настолько отчаялся найти годный движок для документации Type-R, что запилил на коленке свой собствненный генератор сайтика в духе https://github.com/lord/slate. Проблема со всеми тулами, что я находил, была одна и та же - они имеют слишком строгое мнение на тему того, как надо делать сайт. Требуют слишком много времени на то, чтобы с ними возиться. Требуют экспертизы, и "правильного" способа делать вещи. У меня не было на это времени.

Так вот. Нашел абсолютно гениальный генератор статических сайтов. Просто ураган, всегда о таком мечтал. И теперь не надо писать свой.

Короче. Эта штука берет контент в виде markdown с опциональными шапками в yaml, уложенные в иерархию папок (вот он, подход здорового человека, ну наконец-то). Чтобы статически рендерить оный контент, она запускает React-компоненты, которые там вместо шаблонов. А еще, там элементарно цепляется кастомизация рендеринга markdown.

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

Но было бы ошибкой делать на cuttlebelle сайт документации. Ибо, его надо делать на https://docusaurus.io/

Если, конечно, это не библиотека React JSX компонент. Тогда, вне всяких сомнений - это надо делать на https://www.docz.site/

Еще заслуживают упоминания https://www.gatsbyjs.org/ (как самый злоебучий генератор сайтов на React), и https://github.com/nozzle/react-static как альтернатива ему.

https://www.facebook.com/100000008953278/posts/2249905091686434/

Про Gatsby знаю, на остальные посмотрю, спасибо ))

Влад Балин — это тот самый gaperton из ЖЖ?

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

Чего в нем ураганного то?

@slystsev сразу понятно одно: парень любит React

Да

Но какая связь между реактом (который есть за что любить) и статическим сайтом документации?

Я не понял из этого потока мысли. То, что он сначала так нахваливает это cuttlebelle? Там как-то странно написано

Ага, это оно )

Столько всего об генерации документации и прочее. Это конечно хорошо, а как-же содержать это все в актуальной форме? Изменение в API - ищещь статью и правишь. И это дай Бог если разработчик к комиту оставил примечание.

Именно максимальная автоматизация и генерация всего что только можно позволит иметь актуальную доку