FAQ
Hi,

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")?

Thanks,

Simone


------------------------------------------------------
Passa a Infostrada. ADSL e Telefono senza limiti e senza canone Telecom
http://click.libero.it/infostrada

Search Discussions

  • Robert 'phaylon' Sedlacek at Apr 3, 2007 at 10:01 pm

    simonecesano@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

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupcatalyst @
categoriescatalyst, perl
postedApr 3, '07 at 9:27p
activeApr 3, '07 at 10:01p
posts2
users2
websitecatalystframework.org
irc#catalyst

People

Translate

site design / logo © 2022 Grokbase