[Catalyst] Self documenting Controller plugin

[Robert 'phaylon' Sedlacek]

simonecesano at libero.it wrote:
> I'm starting to fiddle around with the idea of a "self documentation"
> plugin for Catalyst, i.e. a plugin that returns the POD documentation
> of a Controller module formatted as HTML.
> 
> That way I do not have to maintain separate documentation, just write
> POD inside the controllers.
> 
> Any ideas or input on features it should have? does it make sense? is
> it OK to have it automatically create a "help" action in every
> controller (sort of like "my/controller/help")?

First of all, I wouldn't put the application manual into the controller
code. In most of my cases, it heavily depends on how the UI on top of
the actions is built. This will possibly also get a PITA once you want
I18N. You surely don't want your translators editing your controller
modules.

I'd probably rather have a custom controller base class like this:

  package MyApp::ControllerBase::Help;
  use strict;
  use base 'Catalyst::Controller';

  sub help: Local {   # or whatever dispatch type you use
      my ($self, $c) = @_;
      $c->stash( template =>
          ($c->config->{help_path} || '') .
          $self->{help_section} .
          ($c->config->{help_extension} || '.html')
      );
  }

  1;

and use it via

  package MyApp::Controller::Foo;
  use strict;
  use base 'MyApp::ControllerBase::Help';

  __PACKAGE__->config( help_section => 'foo' );

  sub foo: Local { }
  sub bar: Local { }

  1;

With 'help_path' set to something like '_help/' in the application
config, this should return, when hit at /foo/help, a rendered
$path_to_templates/_help/foo.html. This is all untested and just a proof
of concept of course, as I don't really know your environment. It all
could be abstracted out more and made more flexible.

.phaylon