Current situation

I like the git-push-triggered documentation generation service of ReadTheDocs. It's nicely layouted, can cope with cross-references between documentation files and generates a nice outline for navigation.

I also have no issue with writing my documentation in Markdown generally, in contrary.

I currently have a Perl based project whose current documentation is written in Markdown and readable online either at ReadTheDocs where it is generated with MkDocs which is written in Python, or at GitHub without any useful table of contents. The man page is currently generated from Markdown with Ronn which is written in Ruby.

Goal

I'd like to upload to above mentioned Perl based project to CPAN, the Comprehensive Perl Archive Network. For that I'd like to have a pure Perl based toolchain for generating the documentation (especially HTML and man page), too.

My research so far

One easy way to achieve that seemed to move all documentation to POD (Perl's Plain Old Documentation Format), because both, pod2html as well as pod2man, exist for a long time and because it's Perl's native documentation format.

While there is quite a lot of POD to something converters, there seem to no equivalent to MkDocs. Pod::Tree's pods2html comes close, but misses relevant features like including the outline of all files in each file or configuring an explicit file order instead of alphabetical for the generated index.

I've also already asked the ReadTheDocs guys if they would support rendering from POD in addition to Markdown, too, but they denied the request with Arguments like "CPAN already does that", but CPAN has no VCS push support at all which was one of my main point.

I've also looked at GitHub Pages since GitHub is able to render POD, but GitHub Pages only supports plain HTML or Jekyll which -- according to itself -- supports a myriad of input formats, but not POD. (And Jekyll is written in Ruby, too, so wouldn't be suitable for local documentation generation either.)

There are other projects similar to MkDocs, but none of them would be an improvement for me, so I don't take them into consideration:

  • Daux: written in PHP and primarily meant for server-side.
  • Beautiful Docs: written in CoffeeScript and hence having way less common and widespread dependencies (CoffeeScript, Node.js and NPM as far as I can see from a first glance) than MkDocs (Python).
  • Flatdocs: Renders Markdown inside the web browser, i.e. requires a browser with JavaScript interpreter as well as JavaScript being enabled. IMHO a fat no-go for documentation.

Current requirements and wishlist items

Hard requirements

It needs to be …

  • written in Perl;
  • Free Software;
  • able to convert multiple POD or Markdown files to multiple HTML files where each HTML file includes a complete index of all files.
  • The order in the file index included in each file needs to be customizable.

Soft requirements

It should be …

Nice-to-have features

I would be nice, if

  • the link texts in the file index included in each file are customizable;
  • it is available as hosted service similar to ReadTheDocs.

Have you considered sticking with Markdown for your actual documentation and adding a POD module to pandoc or to Sphinx to generate your POD files.

  • written in Perl; No
  • Free Software; Yes
  • able to convert multiple POD or Markdown files to multiple HTML files where each HTML file includes a complete index of all files. Yes
  • The order in the file index included in each file needs to be customizable. - I suspect so.
  • Yes. As I wrote, staying with Markdown would be fine, too. Doesn't need to be POD. But Perl is a hard requirement from my point of view, hence POD is a clear alternative to Markdown. I know about Pandoc and I haven't been able to find anything about including a generated index of all pages (only a per-file table of contents) on a first glance. Will have a closer look despite it's not written in Perl, though. Thanks! – Axel Beckert Jul 5 '15 at 18:12
  • Ok, so pandoc does something I didn't expect and think of: It renders multiple Markdown input files into a single (!) HTML file. That's not what I had in mind and not what I want, but seems acceptable in general. – Axel Beckert Jul 5 '15 at 18:19
  • And Sphinx neither seems to support Markdown nor POD. There's a reason why I used MkDocs for ReadTheDocs and not Sphinx. Plus it's written in Python, too. – Axel Beckert Jul 5 '15 at 18:33

Since I haven't found anything which fulfils my requirements, I started to write the according tool myself. It's far from production ready and doesn't have a proper name yet, but very basic functionality is already there.

Your Answer

 
discard

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.