Этот пост уже давно присутствует в моем списке задач. Я видел одного из моих любимых адвокатов FOSS Дана Аллена, работавшего над Awestruct и Aciidoctor, с некоторых пор, и даже некоторые парни из Arquillian запрыгнули на поезд. Пришло время узнать, что это, черт возьми, на самом деле и что нужно, чтобы получить достойную настройку и запуск.
Для начала позвольте мне кратко рассказать о том, что я понял по всем ключевым частям этого удивительного микса. Все дело в документации. Это обширная территория с разными вкусами и процессами. Основная идея здесь заключается в том, что написание документации для разработчиков должно быть легким делом. Он должен быть основан на тексте и, скорее всего, не требует специальной IDE (например, Word;)).
Asciidoc? Asciidoctor? Документация!
Если начать с простого способа написания и форматирования, это приведет к появлению Asciidoc, который в основном представляет собой формат текстового документа для написания заметок, документации, статей, книг, электронных книг, слайд-шоу, веб-страниц, справочных страниц и блогов. Начальный AsciiDoc это и часть программного обеспечения, и разновидность языка разметки. Для запуска вам нужен Python. Не совсем часто используемая вещь на моей стороне вселенной. Но с некоторых пор появился еще один красивый порт. Он называется AsciiDoctor, который представляет собой процессор Ruby с открытым исходным кодом для преобразования разметки AsciiDoc в HTML 5, DocBook 4.5 и другие форматы. Это приближает нас на один шаг к экосистеме Java. Asciidoctor — это нечто большее, чем просто процессор и некоторые таблицы стилей. Проект предоставляет плагины для Maven, Gradle и Guard и пакеты для операционных систем, таких как Fedora. Вы можете узнать об AsciiDoc из Руководства пользователя . Asciidoctor также имеет много документов в Интернете .
Другие наценки — способы написания без слов.
Существуют и другие форматы разметки, которые не требуют ничего, кроме твердого текстового редактора. Наиболее важными из них являются Haml (язык разметки абстракции HTML), Markdown и, возможно, также YAML . В основном у вас есть куча вариантов здесь. В дополнение к этому вы также найдете дополнительные ароматы, такие как GitHub Flavored Markdown . Чтобы сделать длинную историю, сообщество разработчиков с самого начала боролось с необходимостью создания текстовых процессоров с большим весом, и в зависимости от того, в каком сообществе вы находитесь, вы вынуждены использовать один или другой.
Awestruct? Сайты!
Но документация в основном ничто без публикации. Большинство из уже упомянутых подходов к обработке могут публиковать множество различных целевых форматов. Такие вещи, как электронные книги, слайд-шоу, PDF, Word, веб-страницы, справочные страницы и блоги и многое другое. Но с учетом контекста, в котором мы, скорее всего, находимся, не совсем удобно запускать решения на основе Perl на более или менее полной фазе сборки на основе Java. Вот тут-то и вступают Awestruct и Asciidoctor. Awestruct — это инструмент для простого создания нетривиальных статических HTML-сайтов. Основной концепцией Awestruct является концепция структур, в частности, структур Ruby `OpenStruct`. Аспект структуры позволяет произвольным данным без схемы быть привязанными к конкретной странице или всему сайту. Специфичные для сайта данные автоматически загружаются из простых файлов YAML,в то время как данные могут быть представлены на страницах с использованием пролога. В одном предложении: «Он создает веб-сайты из разной разметки и конфигураций» простым способом. Поскольку весь проект и экосистема Ruby в основном построены на системах на основе Linux / Unix, вы вряд ли найдете документацию по настройке этого в Windows.
Давайте перейдем на Microsoft Windows.
Этот блог предназначен для того, чтобы это исправить. Это будет пошаговое руководство, которое должно помочь вам улучшить исходную среду.
Первое, что нужно сделать, это скачать JRuby. Действительно, для Windows доступны нативные версии Ruby, но концепция пакетов для сторонних библиотек в основном построена для поддержки собственных расширений ОС. Используя JRuby, мы используем Java Runtime в качестве уровня адаптации машин, оставаясь при этом близко к экосистеме Ruby. Вы можете скачать JRuby с http://jruby.org/download, Вы найдете различные выпуски и форматы упаковки там. Я выбрал 1.7.4 исполняемый файл Windows x64 и установил его в папку верхнего уровня на моем жестком диске: \ jruby-1.7.4. Если вы разрешите JRuby автоматически устанавливать переменную PATH, указывающую на вашу папку \ bin, все готово. Обязательным условием является наличие установленной JRE. Если нет, то вы, скорее всего (читаете не тот блог), хотите использовать один из установщиков JRuby + JRE.
Чтобы заставить JRuby работать с уже установленной версией Java, сначала нужно проверить, какую версию вы на самом деле используете, набрав:
jruby -v
jruby 1.7.4 (1.9.3p392) 2013-05-16 2390d3b on Java HotSpot(TM) 64-Bit Server VM 1.7.0_25-b16 [Windows 7-amd64]
Результат показывает, какая именно версия JRE используется. Вы можете изменить его, указав переменную окружения JAVA_HOME на другой путь. Для работы с корпоративным прокси потребуется другая переменная среды:
set http_proxy=http://your.proxy.com:3128
Теперь вы почти готовы установить Awestruct. Установка сравнительно проста. Найдите командную строку и введите:
jruby -S gem install awestruct bundler
Это свяжется с менеджером по упаковке и загрузит необходимые библиотеки. Это все. Следующий шаг — создать новую папку где-нибудь, в которой должен размещаться проект вашего сайта. Идите дальше и создайте один (с именем «test2» в этом руководстве) и перейдите в этот каталог с помощью командной строки. Теперь пришло время инициализировать ваш проект по умолчанию, введя:
awestruct --init --framework bootstrap
На данный момент безопасно игнорировать предупреждения. Команда должна создать структуру каталогов, описанную на веб-сайте awestruct . Я получаю ошибку «Отказано в доступе» в моей системе, выдающей эту команду. Мне кажется, что это также безопасно игнорировать. Я подал и выдаю об этом . Это дало вам базовый макет с поддержкой twitter-bootstrap для вашего проекта. Вы также получили «Gemfile» в корневой папке. Gemfiles — это механизм компоновки выборки зависимых библиотек для проекта. Первоначальная версия содержит только необработанный минимум, необходимый для запуска базовой установки. Чтобы выполнить awestruct с меньшим количеством предупреждений и шумов, вы должны добавить некоторые дополнительные зависимости. Откомментируйте строки, начинающиеся с удаления «#»:
gem 'coffee-script' gem 'asciidoctor' gem 'kramdown' gem 'uglifier' gem 'htmlcompressor'
Вы устанавливаете новые пакеты, выпуская:
bundle install
В командной строке. Это снова выбирает некоторые дополнительные библиотеки и помещает их в вашу папку jruby-1.7.4 \ lib \ ruby \ gems \ shared \ gems для использования. Мы почти там. Теперь вы можете запустить встроенный сервер awestruct (WEBrick) с:
awestruct -d
Это по-прежнему выводит кучу предупреждений, но вы уже можете получить доступ к своему веб-сайту по адресу http: // localhost: 4242 /, и вы увидите страницу приветствия awestruct. Теперь нам нужно сделать несколько файлов asciidoc. Создайте новый файл в корне вашего проекта и назовите его hello.adoc со следующим содержанием:
= Hello, AsciiDoc! Doc Writer <doc@example.com> An introduction to http://asciidoc.org. == First Section * item 1 * item 2 [source,ruby] puts "Hello, World!"
Работа в режиме разработки «-d» теоретически должна автоматически восстанавливать страницы. Это на самом деле не работает с моей настройкой. Вместо этого убейте запущенный процесс awestruct и перезапустите его. Также используется [a href = «http://awestruct.org/getting_started/» target = «_ blank» style = «text-decor: none; color: rgb (1, 113, 174); семейство шрифтов: sans-serif ; font-size: 15px; line-height: 21px; «] Rake работает очень хорошо. В любом случае, результат тот же: переход на http: // localhost: 4242 / hello.html отображает ваш великолепный новый веб-сайт, основанный на asciidoc. Поздравляю. Ты готов.
Теперь есть чему поучиться. Вы можете взглянуть на веб-сайт awestruct и найти путь к документации. Вы также можете взглянуть на один из примеров из галереи, Есть несколько расширений, которые делают это еще более интересным. Если я найду время, я буду копаться в деталях в следующих постах.