Hello, Module-Builders.
I'm looking for some advice on options for generating documentation
dynamically with Module::Build. I'm about done with a module I'm calling
Pod::WikiDoc, which extracts wiki-format Pod blocks from .pm files and
produces the corresponding Pod in standalone .pod files. (I finally got fed
up with writing lists of arguments/options, etc. in Pod -- now I can write
my documentation in wiki, and generate the Pod from that.)
I'd like to wire it into the Module::Build process to get run automatically,
rather than as a standalone utility. I've come up with two approaches that
I think might work, and would like feedback, improvements, or alternatives
from the list.
Option 1: Subclass to wrap the ACTION_code method (i.e. do my stuff then
call the parent)
- Approach: call into my module during ACTION_code to generate the .pod
files from the .pm files and add the .pod files to the cleanup list.
- Drawback: My module has to be included in build_requires.
Option 2: Subclass to wrap the ACTION_distdir method
- Approach: call into my module during ACTION_distdir to generate the .pod
files from the .pm files and add the .pod files to the MANIFEST so they get
packaged for distribution. This avoids creating a build_requires dependency.
- Drawback: Pod files aren't available during build for Pod and
Pod-coverage testing or even just to confirm that the Pod was properly
generated.
I rejected the idea of using a .PL file for every module/.pod file -- too
much maintenance headache.
I also rejected (at least at first) using a single, master .PL to find .pm
files and generate .pod because that .PL would need to create a
Module::Build object to add the .pod files to the cleanup list and I was
worried about having a Module::Build object call a .PL which regenerates a
Module::Build object -- probably would work, but I wasn't sure about side
effects.
I haven't tried either approach out yet as I'm new to subclassing
Module::Build and hope to get some directional guidance before spending time
on something that might not work or might not be a good solution for
distribution. If anyone on the list has practical experience with more
dynamic Module::Build approaches, I'd appreciate any insights you can share.
Thanks very much.
Sincerely,
David Golden
-------------------------------------------------------
SF.Net email is sponsored by:
Tame your development challenges with Apache's Geronimo App Server. Download
it for free - -and be entered to win a 42" plasma tv or your very own
Sony(tm)PSP. Click here to play: http://sourceforge.net/geronimo.php
|
