p6doc — попытка написать что-то вроде «perldoc» для Perl 6

HTML-версию этой документации можно найти по адресу https://docs.perl6.org/.

(Если вы просматриваете этот репозиторий через github, большинство файлов будут отображаться неправильно, потому что это Perl 6 Pod, а github предполагает Perl 5 POD).

Установка

Этот модуль доступен через экосистему модулей Perl 6. Используйте

zef install p6doc

чтобы установить двоичные файлы и сделать их доступными в вашем пути выполнения двоичных файлов.

После загрузки запустите

p6doc-index build

для создания индекса.

Использование

С исполняемым файлом Rakudo perl6 в PATH, попробуйте

./bin/p6doc Type::Str

чтобы увидеть документацию для класса Str, или

./bin/p6doc Type::Str.split

чтобы просмотреть документацию по методу split в классе Str. Вы можете пропустить часть ./bin, если установили его через panda или zef. Вы также можете сделать

p6doc -f slurp

чтобы просматривать документацию стандартных функций. В зависимости от скорости вашего диска и версии Rakudo это может занять некоторое время.

Создание HTML-документации

Установите зависимости, выполнив следующие действия в каталоге оформления заказа:

panda installdeps .       # если вы используете panda
zef --depsonly install .  # если вы используете zef

Если вы используете rakudobrew, также выполните следующее, чтобы обновить прокладки для установленных исполняемых файлов:

rakudobrew rehash

В дополнение к зависимостям Perl 6 вам необходимо установить graphviz, который на Debian вы можете установить, запустив

sudo apt-get install graphviz

Чтобы создать веб-страницы документации, просто запустите

$ make html

После того как страницы были созданы, вы можете просмотреть их на своём локальном компьютере, запустив включённую программу app.pl:

$ make run

Затем вы можете просмотреть примеры документации, указав свой веб-браузер на http://localhost:3000.

Вам потребуется как минимум Mojolicious, установленный, и вам понадобится nodejs, чтобы выполнить подсветку.

Требуется помощь!

Perl 6 — это не маленький язык, и документирование требует больших усилий. Любая помощь приветствуется.

Вот несколько способов помочь нам:

• добавить отсутствующую документацию для классов, ролей, методов или операторов;
• добавить примеры использования в существующую документацию;
• отредактировать и исправить документацию;
• сообщить нам об отсутствующей документации, открыв проблемы на github.
• Сделайте git grep TODO в этом репозитории и замените элементы TODO фактической документацией.

На странице Issues есть список текущих проблем и частей документации, которые, как известно, отсутствуют, а CONTRIBUTING кратко объясняет, как начать вносить свой вклад в документацию.

Некоторые примечания:

Вопрос: Почему вы не встраиваете документы в основные источники?
Ответ: Несколько причин:

1. Эта документация предназначена для того, чтобы быть универсальной по отношению к данной версии спецификации, и не обязательно привязана к какой-либо конкретной реализации Perl 6.
2. Обработка встроенных POD реализациями всё ещё немного неравномерна; это позволяет избежать потенциальных воздействий во время выполнения.
3. Отдельный репозиторий на учётной записи perl6 Github приглашает больше потенциальных участников и редакторов.

Вопрос: Должен ли я включать методы из суперклассов или ролей?
Ответ: Нет. Версия HTML уже включает методы из суперклассов и ролей, и сценарий p6doc также будет обучен им.

Вопрос: Под какой лицензией находится этот материал?
Ответ: И код, и документация доступны под лицензией Artistic License 2.0, опубликованной The Perl Foundation. Полный текст см. в файле LICENSE.

Видение

Я хочу, чтобы p6doc и doc.perl6.org стали ресурсом № 1, к которому следует обращаться, когда вы хотите узнать что-то о Perl. 6 feature, будь то из языка или встроенных типов и процедур. Я хочу, чтобы это было полезно каждому Perl 6 программисту.

— Мориц

Список пожеланий:

• Реализации Perl 6 могли бы встраивать теги P<...> в свой исходный код, которые затем встраивали бы соответствующую запись из p6doc. Это позволило бы таким вещам, как &say.WHY, (динамически!) извлекать строку документации из p6doc, без необходимости дублировать документацию в источниках CORE.setting или кодировать документацию в двоичные файлы.

  Пример:

  # В Rakudo's src/core/IO.pm:
  
  #= P<p6doc/&print>
  sub print(|$) { ... }
  
  #= P<p6doc/&say>
  sub say(|$) { ... }
  
  #= P<p6doc/&note>
  sub note(|$) { ... }

LICENSE

Подробности лицензии кода в этом репозитории см. в файле LICENSE.

Этот репозиторий также содержит код, созданный третьими лицами, который может быть лицензирован по другой лицензии. Такие файлы указывают авторские права и условия лицензии в верхней части файла. В настоящее время они включают:

• Библиотеки jQuery и jQuery UI: Copyright 2015 jQuery Foundation и другие участники; MIT License
• Плагин jQuery Cookie: Copyright 2006, 2015 Klaus Hartl & Fagner Brack; MIT License
• Примеры со Stack Overflow MIT License; (ref #1 для 1f7cc4e)