Momentane Situation

Ich mag den durch Git-Push ausgelösten Dokumentationsgenerierungsdienst von ReadTheDocs . Es ist schön gestaltet, kann mit Querverweisen zwischen Dokumentationsdateien umgehen und erzeugt eine schöne Gliederung für die Navigation.

Ich habe auch kein Problem damit, meine Dokumentation im Allgemeinen in Markdown zu schreiben, im Gegenteil.

Ich habe derzeit ein Perl-basiertes Projekt, dessen aktuelle Dokumentation in Markdown geschrieben und online lesbar ist, entweder bei ReadTheDocs , wo es mit MkDocs generiert wird, das in Python geschrieben ist, oder bei GitHub ohne nützliches Inhaltsverzeichnis . Die Manpage wird derzeit von Markdown with Ronn generiert , das in Ruby geschrieben ist.

Ziel

Ich möchte das oben erwähnte Perl-basierte Projekt in CPAN, das Comprehensive Perl Archive Network , hochladen . Dafür hätte ich gerne auch eine reine Perl-basierte Toolchain zum Generieren der Dokumentation (insbesondere HTML und Manpage).

Meine bisherigen Recherchen

Ein einfacher Weg, dies zu erreichen, schien die gesamte Dokumentation in POD (Perl's Plain Old Documentation Format) zu verschieben, da sowohl pod2htmlals auch pod2man, seit langem existieren und weil es das native Dokumentationsformat von Perl ist.

Während es ziemlich viele POD-to-Something-Konverter gibt, scheint es kein Äquivalent zu MkDocs zu geben . Pod::Tree 's pods2html kommt dem nahe, vermisst aber relevante Funktionen wie das Einschließen der Umrisse aller Dateien in jeder Datei oder das Konfigurieren einer expliziten Dateireihenfolge anstelle einer alphabetischen für den generierten Index.

Ich habe die Leute von ReadTheDocs auch schon gefragt, ob sie neben Markdown auch das Rendern von POD unterstützen würden, aber sie haben die Anfrage mit Argumenten wie "CPAN macht das schon" abgelehnt, aber CPAN hat überhaupt keine VCS-Push-Unterstützung, was eine war von meinem Hauptpunkt.

Ich habe mir auch GitHub Pages angesehen , da GitHub POD rendern kann, aber GitHub Pages unterstützt nur einfaches HTML oder Jekyll , das – nach eigenen Angaben – eine Vielzahl von Eingabeformaten unterstützt , aber kein POD. (Und Jekyll ist auch in Ruby geschrieben, wäre also auch nicht für die lokale Dokumentationsgenerierung geeignet.)

Es gibt andere Projekte ähnlich MkDocs , aber keines davon wäre eine Verbesserung für mich, daher berücksichtige ich sie nicht:

• Daux : in PHP geschrieben und hauptsächlich für die Serverseite gedacht.
• Wunderschöne Docs : geschrieben in CoffeeScript und daher weitaus weniger verbreitete und weit verbreitete Abhängigkeiten (CoffeeScript, Node.js und NPM, soweit ich das auf den ersten Blick erkennen kann) als MkDocs (Python).
• Flatdocs : Rendert Markdown im Webbrowser, dh erfordert einen Browser mit JavaScript-Interpreter sowie aktiviertem JavaScript. IMHO ein fettes No-Go für die Dokumentation.

Aktuelle Anforderungen und Wunschliste

Harte Anforderungen

Es muss sein …

• geschrieben in Perl;
• Freie Software ;
• in der Lage, mehrere POD- oder Markdown-Dateien in mehrere HTML-Dateien zu konvertieren, wobei jede HTML-Datei einen vollständigen Index aller Dateien enthält.
• Die Reihenfolge im Dateiindex, der in jeder Datei enthalten ist, muss anpassbar sein.

Weiche Anforderungen

Es sollte sein …

• auf CPAN verfügbar .

Nice-to-have-Funktionen

Ich wäre nett, wenn

• die Linktexte im Dateiindex, die in jeder Datei enthalten sind, sind anpassbar;
• es ist ähnlich wie ReadTheDocs als gehosteter Dienst verfügbar .