perlgib is Perl's alternative documentation and test manager.
perlgib generates HTML, Markdown and Pod documentation and runs tests from Perl code comment lines.
$ perl Makefile.pl
$ make dist
$ VERSION=$(perl -Ilib -le 'require "./lib/Perl/Gib.pm"; print $Perl::Gib::VERSION')
$ cpanm Perl-Gib-$VERSION.tar.gz
Simply run perlgib doc
- HTML files including an index file are placed in
doc
- or perlgib test
from within your Perl project. Beside Perl modules
also Markdown files are processed.
For further information about the command line tool perlgib
see the
following help output.
Usage:
perlgib --help|-h | --man|-m | --version|-v
perlgib [OPTIONS] doc | test [OPTIONS]
Options:
base:
--help|-h
Print short usage help.
--man|-m
Print extended usage help.
--version|-v
Print version string.
--library-path PATH
Directory with documents (Perl modules, Markdown files) to
process, default lib in current working directory.
--library-name NAME
Library name.
doc:
Build library documentation.
--output-path
Documentation output path, default doc in current working
directory.
--output-format html|markdown|pod|all
Documentation output format, default html.
--document-private-items
Document private items.
--document-ignored-items
Document ignored items (#[ignore(item)]).
--ignore-undocumented-items
Ignore undocumented items.
--no-html-index
Prevent creating of html index.
test:
Execute documentation tests.
The Perl::Gib API documentation is generated by running perlgib
from
within this Perl distribution.
Perl::Gib iterates through the library path and processes following item documentation comment lines in the found Perl Modules.
- package (module) itself
- subroutines (methods)
If the postmodern object system for Perl 5 Moose is detected, following additional items are processed.
- attributes
has
- method modifiers
before
,after
,around
,augment
,override
.
A package documentation comment line starts with two hashes followed by an exclamation mark.
##! Package documentation comment line.
The documentation comment block must be placed after the namespace line.
package Acme::Corporation;
##! The Acme Corporation is a fictional corporation that features
##! prominently in the Road Runner/Wile E. Coyote animated shorts as a
##! running gag featuring outlandish products that fail or backfire
##! catastrophically at the worst possible times.
A documentation comment line for all the other above listed Perl module items starts with three hashes.
### Other item documentation comment line.
The documentation comment block must be placed before the item.
### Acme American wrought anvils.
has 'anvils' => (
is => 'ro',
isa => 'Int',
default => 10,
);
### Hit an anvil.
###
### It rings like a bell.
sub hit {
my $self = shift;
return "ring";
}
A test block starts and ends with three apostrophe.
### ```
Test blocks must be placed in a subroutine / method documentation comment block.
### Test the wrought anvil.
###
### ```
### my $bell = hit();
###
### is( $bell, "ring");
### ```
sub hit {
...
The package itself and Test::More are included by default. The code is placed in a subtest named by the subroutine. The final module test scipts are run by prove.
All private items - item name starting with an underscore - are ignored. Items with a first documentation comment line contenting a pseudo method are also ignored.
##! #[ignore(item)]
The whole package (module) is skipped.
### #[ignore(item)]
This ignores the followed item.
Further licenses see lib/Perl/Gib/resources/assets
css/highlight.css
css/normalize.css
js/highlight.min.js