Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

Displaying POD like MetaCPAN

by Bod (Parson)
on Nov 07, 2023 at 21:50 UTC ( [id://11155447] : perlquestion . print w/replies, xml ) Need Help??

Bod has asked for the wisdom of the Perl Monks concerning the following question:

Do you know of any modules or services that can display POD in the same (or similar) style as MetaCPAN?

We want to document internal modules consistently and it seems sensible to keep the layout and style in one with public modules.

Replies are listed 'Best First'.
Re: Displaying POD like MetaCPAN
by Haarg (Priest) on Nov 08, 2023 at 07:57 UTC

    Rendering from Pod to HTML is done using MetaCPAN::Pod::XHTML. This is based on Pod::Simple::XHTML, with some adjustments. There is then some post-processing to restrict what HTML can be used, and to link images correctly.

    Syntax highlighting is done using JavaScript, and there are CSS rules to style everything.

Re: Displaying POD like MetaCPAN
by tobyink (Canon) on Nov 08, 2023 at 10:57 UTC

    A while back, I wrote TOBYINK::Pod::HTML which generates fairly clean HTML or XHTML, and syntax highlights code using PPI::HTML, Syntax::Highlight::RDF, or Syntax::Highlight::Engine::Kate depending on the language being syntax highlighted (because it doesn't just support Perl!).

    It comes with a command-line tool allowing you to do:

    pod2html-tobyink --code_highlighting --pretty --output=xhtml path/to/d +oc.pod >path/to/doc.html

    But you probably want to write your own command-line tool if you want to pass in different options for code highlighting colours, etc.

    Also consider Web::PerlDistSite which wraps TOBYINK::Pod::HTML and provides a static-site generator for quickly creating flashy websites for a Perl distribution. The documentation is a little sparse, but once you've set it up once, it's fairly easy to use.

    This is what is used by, for example, the Type::Tiny website.

Re: Displaying POD like MetaCPAN
by NERDVANA (Deacon) on Nov 07, 2023 at 23:01 UTC
    While a local CPAN mirror with your in-house modules added to it and running MetaCPAN on front is probably the *best* solution, the quickest solution is probably to make LWP calls to MetaCPAN's Pod Renderer and cache the results :-)

    The next better step would be to dive into MetaCPAN's source code and find the controller for that pod2html URL, which probably shows you a minimalist way to get the job done, which you could then port to your own web app, maybe installing MetaCPAN libraries as a dependency.

Re: Displaying POD like MetaCPAN
by LanX (Saint) on Nov 07, 2023 at 22:09 UTC
Re: Displaying POD like MetaCPAN
by kevbot (Vicar) on Nov 08, 2023 at 07:01 UTC

      So many options...

      Overwhelmed by choice is the downside of TIMTOWTDI!