Writing documentation is sometimes hard but inevitable. If you write code which is published on the CPAN you can always access the documentation through search.cpan.org. For those cases where you cannot publish your code on the CPAN it would be great if you had a web site like CPAN where you can access the documentation. For this reason I wrote Pod::Browser a while back. Pod::Browser is a browser for all your local modules and all the modules from the CPAN. The interface is rendered by ExtJS, a powerful JavaScript framework.

Pod::Browser

After installing Pod::Browser and running the server (pod_browser_server.pl) you should be able to access the browser via http://localhost:3000. On the right hand side of the page is a tree which contains all the modules installed on your system. The main page contains a search box where you can search the CPAN via it’s XML interface. If you open a module which is also installed on your system, the local pod will be served. Otherwise the pod is read from the CPAN. Each module has its own ExtJS tab. This allows to have multiple documents open at the same time in a single browser window. The table of contents is shown in the upper left panel.

Since this browser has been implemented as a single Catalyst controller, you can simply create an empty controller in your application and use Catalyst::Controller::POD as base class:

package MyApp::Controller::Docs;
 
  use strict;
  use warnings;
  use base 'Catalyst::Controller::POD';
  __PACKAGE__->config(
    inc        => 1,
    namespaces => [qw(Catalyst::Manual*)],
    self       => 1,
  );
  1;

This will make the documentation to your application avaiable from /docs. The pod tree will also contain all the modules which are listed in the namespaces config attribute (in this case Catalyst::Manual).

For more information on Pod::Browser and Catalyst::Controller::POD please read the documentation on the CPAN.

Warning:

If you set inc to 1 and leave the namespaces parameter blank it can take a while until all modules are indexed and presented in your browser. Be either patient or restrict the namespace to a sane subset of your modules.