search

rjbs / Pod-Weaver

recombine pod documents into awesomer pod documents
26 stars 28 forks source link

Pod::Weaver::Section::GenerateSection: allow filename list #53

Open Ovid opened 2 years ago

Ovid commented 2 years ago

I've tried to find what I'm looking for, but I've failed, and this looks like the closest match. If I've missed something, my apologies.

In Pod::Weaver::Section::GenerateSection, it appears that we can generate sections in every document, or main_module_only. For MooseX::Extended, I have several common snippets of POD that should be shared with some modules, but not all. For example:

[GenerateSection / ATTRIBUTE]
head = 1
file=lib/MooseX/Extended.pm
file=lib/MooseX/Extended/Role.pm
file=lib/MooseX/Extended/Manual/Tutorial.pm
text = ...

[GenerateSection / CLONING]
file=lib/MooseX/Extended.pm
file=lib/MooseX/Extended/Role.pm
file=lib/MooseX/Extended/Manual/Tutorial.pm
file=lib/MooseX/Extended/Manual/Cloning.pod
text - ...

And so on ...

In your POD, you might even specify the location with a =for :ATTRIBUTE section.

This would tremendously reduce my maintenance burden.

In fact, it would be nice if we could store the POD outside of the weaver.ini:

[GenerateSection / ATTRIBUTE]
head = 1
file=lib/MooseX/Extended.pm
file=lib/MooseX/Extended/Role.pm
file=lib/MooseX/Extended/Manual/Tutorial.pm
source = templates/attributes.pod           ;  <-- look ma, no data :)
karenetheridge commented 2 years ago

I use Pod::Weaver::Section::AllowOverride in a lot of distributions to either override or append to a default pod section that the weaver.ini provides.

Here are some of my dists that you can look at for examples of its use:

Acme-Pi Catalyst-Plugin-Session-State-Stash Data-Page Devel-Leak-Object Devel-REPL HTML-Tree JSON-Schema-Modern JSON-Schema-Tiny Module-Metadata Mojolicious-Plugin-OpenAPI-Modern Moose MooseX-AttributeHelpers MooseX-Daemonize OpenAPI-Modern Sub-Name Test-JSON-Schema-Acceptance

Ovid commented 2 years ago

@karenetheridge Thank you! I'll check those out.