Эквивалент MkDocs, написанный на Perl, для преобразования деревьев Markdown или POD в HTML с индексом в каждом файле.

Текущая ситуация

Мне нравится сервис ReadTheDocs для генерации документации с помощью git-push . Он красиво оформлен, может работать с перекрестными ссылками между файлами документации и создает хороший план для навигации.

У меня также нет проблем с написанием моей документации в Markdown, как правило, наоборот.

В настоящее время у меня есть проект на основе Perl , текущая документация которого написана в Markdown и доступна для чтения в Интернете либо на ReadTheDocs, где она создается с помощью MkDocs , написанного на Python, либо на GitHub без какого-либо полезного оглавления . В настоящее время справочная страница генерируется из Markdown с помощью Ronn , написанного на Ruby.

Цель

Я хотел бы загрузить вышеупомянутый проект на основе Perl в CPAN, Comprehensive Perl Archive Network . Для этого я хотел бы иметь чистый набор инструментов на основе Perl для создания документации (особенно HTML и справочной страницы).

Мои исследования до сих пор

Одним из простых способов добиться этого, казалось, было перевести всю документацию в POD (Perl's Plain Old Documentation Format), потому что оба, pod2htmlа также pod2man, существуют уже давно и потому что это родной формат документации Perl.

Хотя конвертеров POD во что-то довольно много, эквивалента MkDocs , похоже, нет . Pod::Tree pods2html подходит близко, но упускает важные функции, такие как включение структуры всех файлов в каждый файл или настройка явного порядка файлов вместо алфавитного для сгенерированного индекса.

Я также уже спрашивал ребят из ReadTheDocs, будут ли они поддерживать рендеринг из POD в дополнение к Markdown, но они отклонили запрос с такими аргументами, как «CPAN уже делает это», но CPAN вообще не поддерживает push-уведомления VCS, что было одним из них. моей основной мысли.

Я также смотрел на GitHub Pages , так как GitHub может отображать POD, но GitHub Pages поддерживает только обычный HTML или Jekyll , который, по его словам, поддерживает множество входных форматов , но не POD. (Кроме того, Jekyll написан на Ruby, поэтому он также не подходит для создания локальной документации.)

Есть и другие проекты, похожие на MkDocs , но ни один из них не стал бы для меня улучшением, поэтому я их в расчет не беру:

  • Daux : написан на PHP и в первую очередь предназначен для серверной части.
  • Beautiful Docs : написаны на CoffeeScript и, следовательно, имеют менее распространенные и распространенные зависимости (CoffeeScript, Node.js и NPM, насколько я могу судить с первого взгляда), чем MkDocs (Python).
  • Flatdocs : визуализирует Markdown внутри веб-браузера, т.е. требует браузера с интерпретатором JavaScript, а также с включенным JavaScript. ИМХО жирный отказ от документации.

Текущие требования и элементы списка пожеланий

Жесткие требования

Это должно быть…

  • написан на Perl;
  • Бесплатное программное обеспечение ;
  • возможность конвертировать несколько файлов POD или Markdown в несколько файлов HTML, где каждый файл HTML включает полный индекс всех файлов.
  • Порядок в файловом индексе, включенном в каждый файл, должен быть настраиваемым.

Мягкие требования

Так должно быть …

Приятные функции

Я был бы хорош, если бы

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

Ответы (2)

Думали ли вы о том, чтобы придерживаться Markdown для вашей фактической документации и добавлять модуль POD в pandoc или Sphinx для создания ваших файлов POD.

  • написан на Perl; Нет
  • Свободное программное обеспечение; Да
  • возможность конвертировать несколько файлов POD или Markdown в несколько файлов HTML, где каждый файл HTML включает полный индекс всех файлов. Да
  • Порядок в файловом индексе, включенном в каждый файл, должен быть настраиваемым. - Подозреваю, что да.
Да. Как я уже писал, оставаться с Markdown тоже было бы неплохо. Не обязательно POD. Но, с моей точки зрения, Perl является жестким требованием, поэтому POD является явной альтернативой Markdown. Я знаю о Pandoc, и мне не удалось найти ничего о включении сгенерированного индекса всех страниц (только оглавление для каждого файла) на первый взгляд. Однако посмотрю повнимательнее, несмотря на то, что он написан не на Perl. Спасибо!
Итак, pandoc делает то, чего я не ожидал и о чем не думал: он отображает несколько входных файлов Markdown в один (!) HTML-файл. Это не то, что я имел в виду и не то, чего я хочу, но в целом кажется приемлемым.
И Sphinx, похоже, не поддерживает ни Markdown, ни POD. Есть причина, по которой я использовал MkDocs для ReadTheDocs, а не Sphinx. Кроме того, он тоже написан на Python.

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

Эквивалент MkDocs, написанный на Perl, для преобразования деревьев Markdown или POD в HTML с индексом в каждом файле.
СпросиСетьПолитика конфиденциальности1y, 0v