Getting started with Pod::Weaver
•Download as KEY, PDF•
1 like•2,681 views
Pod::Weaver is a tool that uses templates to generate documentation from POD source. It addresses issues like redundant documentation by following rules defined in a weaver.ini template file. This allows it to generate leaner POD that removes unneeded sections like NAME, VERSION, and AUTHORS. It also defines subroutines, methods, and attributes more cleanly. Pod::Weaver supports various output formats through different templates and can be used via Dist::Zilla or directly with the podweaver command.
More Related Content
What's hot
What's hot (17)
Viewers also liked
Similar to Getting started with Pod::Weaver
Similar to Getting started with Pod::Weaver (20)
Recently uploaded
Recently uploaded (20)
Getting started with Pod::Weaver
- 1. Pod::Weaver Module author: Ricardo Signes Talk author: Joshua Keroes Date: 13 Sep 2012
- 2. Who likes to write documentation? http://www.flickr.com/photos/bensonkua/2687804310/ 2
- 4. What sucks about documentation? It violates the DRY rule. 3
- 5. What sucks about documentation? It violates the DRY rule. 3
- 6. What else sucks? 4
- 7. What else sucks? POD is too verbose. =head1 FUNCTIONS =over =item frowny() Returns a frowny face. =back 4
- 8. What else sucks? Let it all out. =head1 COPYRIGHT AND LICENSE Copyright (c) 1901 Fergie T. Sumtin. All rights reserved. 5
- 9. Templates to the rescue 6
- 10. Templates to the rescue POD::Weaver uses a template. It’s called weaver.ini. 6
- 12. weaver.ini [@Default] [@CorePrep] [Collect / ATTRIBUTES] command = attr [Name] [Collect / METHODS] [Version] command = method [Region / prelude] [Generic / SYNOPSIS] [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region / postlude] [Authors] 8
- 13. weaver.ini [@Default] [EnsurePod5] [Collect / ATTRIBUTES] [H1Nester] command = attr [Name] [Collect / METHODS] [Version] command = method [Region / prelude] [Generic / SYNOPSIS] [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region / postlude] [Authors] 9
- 14. weaver.ini [@Default] [EnsurePod5] [Collect / ATTRIBUTES] [H1Nester] command = attr [Name] [Collect / METHODS] [Version] command = method [Region / prelude] [Collect / FUNCTIONS] [Generic / SYNOPSIS] command = func [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region / postlude] [Authors] 10
- 15. weaver.ini [@Default] [EnsurePod5] [Collect / ATTRIBUTES] [H1Nester] command = attr [Name] [Collect / METHODS] [Version] command = method [Region / prelude] [Collect / FUNCTIONS] [Generic / SYNOPSIS] command = func [Generic / DESCRIPTION] [Leftovers] [Generic / OVERVIEW] [Region / postlude] [Authors] 11
- 16. [NAME] =head1 NAME Some::Package::Name - just a package 12
- 17. [NAME] =head1 NAME Some::Package::Name - just a package # PODNAME: Some::Package::Name # ABSTRACT: just a package 13
- 18. [NAME] =head1 NAME Some::Package::Name - just a package package Some::Package::Name # ABSTRACT: just a package 14
- 20. [Generic / SYNOPSIS] [Generic / DESCRIPTION] [Generic / OVERVIEW] =head1 SYNOPSIS my $p = Some::Package::Name->new; say $p; =head1 DESCRIPTION A module that knows it’s own package name. 16
- 21. [Collect / FUNCTIONS] command = func =head1 FUNCTIONS =over =item binge() eats arguments =item purge() returns eaten args =back 17
- 22. [Collect / FUNCTIONS] command = func =head1 FUNCTIONS =over =item binge() =func binge() eats arguments eats arguments =item purge() =func purge() returns eaten args returns eaten args =back 18
- 23. [Collect / METHODS] command = method =head1 METHODS =over =item new() creates an object =item spawn() spawns an object =back 19
- 24. [Collect / METHODS] command = method =head1 METHODS =over =item new() =method new() creates an object creates an object =item spawn() =method spawn() spawns an object spawns an object =back 20
- 25. [Collect / ATTRIBUTES] command = attr =head1 ATTRIBUTES =over =item torches() number of torches =item matches() number of matches =back 21
- 26. [Collect / ATTRIBUTES] command = attr =head1 ATTRIBUTES =over =item torches() =attr torches() number of torches number of torches =item matches() =attr matches() number of matches number of matches =back 22
- 27. [Region / prelude] =begin :prelude weaver.ini … [Name] =end :prelude [Version] [Region / prelude] =for :prelude … [Generic / SYNOPSIS] [Generic / DESCRIPTION] … 23
- 28. [Leftovers] =head1 SUPPORT weaver.ini For support, please … send a self-addressed, stamped envelope to: [Leftovers] Joshua Keroes [Region / postlude] Somewhere in [Authors] Portland, OR [Legal] 24
- 29. [Region / postlude] =begin :postlude weaver.ini … … =end :postlude [Leftovers] [Region / postlude] =for :postlude … [Authors] [Legal] 25
- 30. [Authors] =head1 AUTHORS weaver.ini Colette O’Day … <colette@example.com> [Leftovers] [Region / postlude] [Authors] [Legal] 26
- 31. [Legal] =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2012 by Joshua Keroes. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 27
- 32. Let’s sum up. 28
- 33. Leaner POD No more NAME No more VERSION No more AUTHORS No more COPYRIGHT AND LICENSE 29
- 34. Leaner POD Cleaner subroutine definitions =func =method =attr 30
- 35. Beyond @Default
- 36. Lists, the lazy way weaver.ini [@Default] [-Transformer] transformer = List 32
- 37. Lists =head1 SEE ALSO =over 4 =item * L<Your::Module> =item * L<Your::Package> =back 33
- 38. Pod::Weaver bullet lists =head1 SEE ALSO =head1 SEE ALSO =over 4 =item * =for :list L<Your::Module> * L<Your::Module> =item * * L<Your::Package> L<Your::Package> =back 34
- 39. Pod::Weaver numeric lists =head1 SEE ALSO =head1 SEE ALSO =over 4 =item * =for :list L<Your::Module> 1. L<Your::Module> =item * 1. L<Your::Package> L<Your::Package> =back 35
- 40. Pod::Weaver frontends 36
- 41. Dist::Zilla dist.ini [PodWeaver] … 37
- 42. App::podweaver Great for troubleshooting; bypassing Dist::Zilla podweaver lib/path/to/file.pm 38
- 43. References This talk at SlideShare: http://xrl.us/jkeroespw Dist::Zilla + Pod::Weaver http://xrl.us/dzilpw What is Pod::Weaver 1? http://xrl.us/rjbspw1 What is POD::Weaver 2? http://xrl.us/rjbspw2 Falling in love with Pod::Weaver http://xrl.us/lovepw 39
Editor's Notes
- \n
- Show of hands and wild cheering please.\n(If >1: hire this champ)\n(If 0: typical. Fortunately, Pod::Weaver can help)\n\n
- Why don&#x2019;t we like to write docs?\nDRY. Heck, we already wrote the code, right?\nBeyond that, every module file in every module must have a NAME section. And an ABSTRACT. And they should have a COPYRIGHT, LICENSE, and AUTHOR(s), too. There&#x2019;s a lot of repeated effort.\n
- Why don&#x2019;t we like to write docs?\nDRY. Heck, we already wrote the code, right?\nBeyond that, every module file in every module must have a NAME section. And an ABSTRACT. And they should have a COPYRIGHT, LICENSE, and AUTHOR(s), too. There&#x2019;s a lot of repeated effort.\n
- Should we really have to start a FUNCTIONS section? Is it a head1 or a head2? Why do we have to indent? Or remember to stop indenting, for that matter? And what if we want to intermingle POD with code?\n
- Should we really have to start a FUNCTIONS section? Is it a head1 or a head2? Why do we have to indent? Or remember to stop indenting, for that matter? And what if we want to intermingle POD with code?\n
- Why should you have to keep the copyright current? Honestly, we have a computer here.\n\n
- Know what Perl's good at? Templating. Just count the number of template-related modules on CPAN. viz. http://mapofcpan.org/\n
- weaver.ini is the template. Let&#x2019;s take unwrap things a few levels. Default is a Pod::Weaver::PluginBundle::Default. The @-sign means PluginBundle instead of Plugin.\n
- Let&#x2019;s unwrap the CorePrep PluginBundle\n
- Validate POD and make sure all sub-elements are nested under =head1&#x2019;s. Good housekeeping, basically.\n
- Undocumented treasure!\n
- voila, the whole default template. Barring the two housekeeping plugins, the rest are in order. Let&#x2019;s figure out what they do.\n
- \n
- Admittedly, this takes more typing. Fortunately, we can do better.\n
- You need either a PODNAME or a package. The rule of thumb is to use PODNAME for programs and to package for modules.\n
- Automatic and painless. podweaver gets it from a META.json or META.yml file. Under dzil, it depends which plugins are loaded in dist.ini, but that&#x2019;s getting ahead of things.\n
- Think of the GENERIC plugin as a pass-through. These three sections, named above, and their contents will pass through P::W relatively unharmed.\n
- The collect plugin fetches and assembles sets of things. \n
- PW will add the section header and add the indenting; we just list the functions and what they do.\n
- The method collection uses the new =method keyword....\n
- \n
- Like Moose, Mouse, Moo, or Mo? =attr behaves just like the other collects. As with the other examples... Speaking of which, there are two plugins on CPAN you may find useful, one that adds an EXTENDS section; the other a CONSUMES section for Moose roles.\n
- the shorthand on the right will generate the POD on the left.\n
- Do you want to add generic/text before the synopsis? Text found here between a preludes =begin and =end or after a =for will be moved to the prelude location. This has to be generic text. I wasn&#x2019;t able to add commands like =head1 successfully. We&#x2019;ll look at another section that can handle this shortly.\n
- Leftovers come before the postlude region. \n
- Just like the prelude, the postlude will move generic/text after the leftovers.\n
- Automatic. podweaver gets it from META.json or META.yml. Under dzil, it depends which plugins are loaded in dist.ini.\n
- Automatic. podweaver gets it from META.json or META.yml. Under dzil, it depends which plugins are loaded in dist.ini.\n
- \n
- \n
- \n
- \n
- \n
- \n
- \n
- The numbers start at one and are auto-incremented.\n
- \n
- Add one line to run Pod::weaver during `dzil build`.\n
- \n
- \n