Situación actual

Me gusta el servicio de generación de documentación activado por git-push de ReadTheDocs . Tiene un diseño agradable, puede hacer frente a las referencias cruzadas entre los archivos de documentación y genera un esquema agradable para la navegación.

Tampoco tengo ningún problema con escribir mi documentación en Markdown en general, al contrario.

Actualmente tengo un proyecto basado en Perl cuya documentación actual está escrita en Markdown y se puede leer en línea en ReadTheDocs , donde se genera con MkDocs, que está escrito en Python, o en GitHub sin ninguna tabla de contenido útil . La página del manual se genera actualmente a partir de Markdown con Ronn , que está escrita en Ruby.

Objetivo

Me gustaría cargar el proyecto basado en Perl mencionado anteriormente en CPAN, la red integral de archivos de Perl . Para eso, me gustaría tener una cadena de herramientas puramente basada en Perl para generar la documentación (especialmente HTML y la página de manual) también.

Mi investigación hasta ahora

Una manera fácil de lograr eso parecía mover toda la documentación a POD (Perl's Plain Old Documentation Format), porque ambos, pod2htmlasí como pod2man, existen desde hace mucho tiempo y porque es el formato de documentación nativo de Perl.

Si bien hay muchos convertidores de POD a algo, parece que no hay equivalente a MkDocs . Pods2html de Pod::Tree se acerca, pero pierde características relevantes como incluir el esquema de todos los archivos en cada archivo o configurar un orden de archivos explícito en lugar de alfabético para el índice generado.

También les pregunté a los muchachos de ReadTheDocs si admitirían la renderización desde POD además de Markdown, pero negaron la solicitud con argumentos como "CPAN ya hace eso", pero CPAN no tiene soporte de VCS push en absoluto, que era uno de mi punto principal.

También miré las páginas de GitHub , ya que GitHub puede generar POD, pero las páginas de GitHub solo admiten HTML simple o Jekyll que, según él mismo, admite una gran cantidad de formatos de entrada , pero no POD. (Y Jekyll también está escrito en Ruby, por lo que tampoco sería adecuado para la generación de documentación local).

Hay otros proyectos similares a MkDocs , pero ninguno de ellos sería una mejora para mí, por lo que no los tomo en consideración:

• Daux : escrito en PHP y destinado principalmente al lado del servidor.
• Beautiful Docs : escrito en CoffeeScript y, por lo tanto, tiene dependencias mucho menos comunes y generalizadas (CoffeeScript, Node.js y NPM por lo que puedo ver a primera vista) que MkDocs (Python).
• Flatdocs : muestra Markdown dentro del navegador web, es decir, requiere un navegador con un intérprete de JavaScript y JavaScript habilitado. En mi humilde opinión, un gordo no-ir para la documentación.

Requisitos actuales y artículos de la lista de deseos

Requisitos estrictos

Necesita ser …

• escrito en Perl;
• software libre ;
• capaz de convertir múltiples archivos POD o Markdown a múltiples archivos HTML donde cada archivo HTML incluye un índice completo de todos los archivos.
• El orden en el índice de archivos incluido en cada archivo debe ser personalizable.

Requisitos blandos

Debería ser …

• disponible en CPAN .

Características agradables de tener

Sería bueno, si

• los textos de los enlaces en el índice de archivos incluidos en cada archivo son personalizables;
• está disponible como servicio alojado similar a ReadTheDocs .