Как сделать файл README модуля Perl совместимым с дисплеем Github Markdown?

Я создал файл README в модуле Perl в Markdown. Github рассматривает этот файл README как обычный текст. Я попробовал переименовать файл в "README.md", который отлично смотрится в Github, но невидим для инструментов Perl, которые ищут файл с именем "README".

Есть ли способ, которым я могу иметь как файл README, так и мое форматирование Markdown корректно интерпретироваться Github?

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

Спасибо за вашу помощь.

ОТВЕТЫ

Ответ 1

Отформатируйте README в pod, переименуйте его README.pod, а затем работает в обоих местах! Пример

В моих целях я на самом деле просто создаю свой README.pod из основного блока, выполнив

$ podselect lib/My/Main/Module.pm > README.pod

Одно предостережение, называемое внешними ссылками, работает некорректно L<GitHub|http://github.com>, к сожалению, указывает на search.cpan.org, который ищет модуль GitHub. Я попытался сообщить им об этом сбое, но это ни к чему. Вместо этого вы можете просто использовать простые внешние ссылки (т.е. GitHub: L<http://github.com>), и они работают нормально.

Хорошие новости, похоже, они исправили это с момента последнего проверки!

Просто вопрос, какие части инструментария Perl ожидают файла README? Если вы имеете в виду включение его в свой tarball, просто обязательно добавьте файл в свой MANIFEST, и он должен быть включен.

Ответ 2

Слышали ли вы о POD? Это стандартный инструмент документации на Perl. POD - это простой текстовый формат документации, который действительно живет в вашем коде. Одна из команд, которые поставляются с perl, - perldoc. Вы можете использовать его для получения информации о любой команде Perl. Попробуйте следующее:

$ perldoc File::Find
$ perldoc -f split

Все модули Perl в CPAN должны содержать документацию POD. Фактически, именно так построены веб-страницы CPAN.

Итак, где я собираюсь с этим и как это вам поможет?

Вы должны включить документацию POD в свою программу Perl. Затем вы можете использовать команду pod2text, чтобы создать README для своей программы Perl:

$ pod2text myperl.pl > README

Это относится к половине вашей проблемы.

Другая половина немного сложнее. Вам необходимо установить из CPAN Pod::Markdown в вашей системе. Затем вы можете запустить команду pod2markdown, которая поставляется вместе с этим модулем для создания версии уценки вашего файла:

$ pod2markdown myperl.pl > README.md

Результаты:

  • Ваша документация живет, как и должно быть, в вашей программе Perl.
  • Пользователи могут использовать программу perldoc для распечатки полной документации вашей программы.
  • Вы можете использовать инструмент pod2text для создания вашего файла README.
  • Вы можете использовать инструмент pod2markdown для создания вашего файла README.md.
  • В качестве бонуса вы можете использовать модуль Pod:: Usage, который поставляется с Perl, чтобы показать документацию POD (или биты и фрагменты it) в качестве справочного текста, который отображается, когда пользователь запускает вашу программу с параметром -help.

Итак, в одном месте, где живет ваша документация, и вы используете пару вспомогательных программ для создания файлов Github и любых необходимых Perl-инструментов.

Ответ 3

Если вы не против использования Dist::Zilla, вы можете в значительной степени избавиться от полного поддержания README. Например Dist::Zilla::Plugin::ReadmeFromPod может создать ваш файл README, извлекая Pod из вашего основного модуля. Это означает, что вам больше не нужно писать README.

Я никогда не пробовал это самостоятельно, но вы могли бы посмотреть на что-то вроде Dist::Zilla::Plugin::ReadmeMarkdownFromPod, чтобы автоматически создавать README в методе уценки.

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

Ответ 4

Другое решение, если вы действительно хотите распространять свой модуль с помощью Markdown README, который не связан с Pod, заключается в следующем:

  • переименуйте файл README в README.md
  • обновить предыдущее изменение в файле MANIFEST

Я думаю, что это может быть интересное решение, потому что больше людей знают синтаксис Markdown, чем Pod. Поскольку цель файла README должна быть прочитана кем угодно, Markdown следует рассмотреть.

Ответ 5

Единственный вариант, который я мог придумать, - это как README, так и README.md, но я бы предпочел не использовать вручную два файла в синхронизации.

Затем автоматически синхронизировать их?