Dist::Zilla::Plugin::LocalHTML - create CSS-rich HTML pages from the POD-aware files for local browsing
version v0.2.5
# dist.ini [LocalHTML] local_prefix = Dist::Zilla:: local_preifx = MyProject\b dir = html_local ; where to create HTML files ignore = bin/myscript1 ; what input file to ignore ignore = bin/myscript2 ; another input to ignore
This plugin is based upon Dist::Zilla::Plugin::Pod2Html. Check for more info below.
This plugin generates HTML pages from the POD files and puts them into the distribution in a separate directory (not as a tree of files but flatten). The created HTML pages have the same (or, at least, similar) style as the modules' documentation shown at CPAN. They're also suitable for local browsing meaning linking between pages is local to the file system meaning that pages are browsable without any webserver or posting a module to CPAN. This could be especially handy for developers using unicode in their docs as sometimes it is not displayed correctly with perldoc – like on macOS systems.
It creates HTML pages from all files in the lib and bin directory that contain a POD section and that have .pm or .pl extension or that have the word perl in their first line. The plugin is run after other plugins that may munge files and create the POD sections (such as PodWeaver).
lib
bin
.pm
.pl
perl
The plugin overrides Pod::Simple::HTML link generation. By distinguishing local and remote links it generates either a simple reference to local filesystem, or a reference to metacpan.org. Link is conisdered local if there is a corresponding file for the original L<> Pod tag. For example, of the following to links:
L<>
L<Local::Project::Module> L<Local::Project::NoModule>
the first one is considered local if there is file lib/Local/Project/Module.pm; the second one would get linked to metacpan.org if there is no file lib/Local/Project/NoModule.pm.
Link type could additionally be determined by "local_prefix" configuration variable.
dir
This attribute changes the destination of the generated HTML files. It is a directory (or even a path) relative to the distribution root directory. Default value is docs. For example:
docs
[LocalHTML] dir = docs/html
local_prefix
What modules to consider as local - i.e. part of the current project. Few prefixes could be defined. Each one could be a regexp expression. A module is considered local if it matches against one of the local prefixes. Note that match is done agains the beginning of module name.
[LocalHTML] local_prefix=My::Project:: local_prefix=My\d::Project\b
The above expressions will match against:
NOTE There is no way yet to define local status for files other that modules. Solution is planned for future.
pod2html_class
Class to be used for HTML generation. Must be a descendant of Pod::Simple::HTML. Dist::Zilla::Plugin::LocalHTML::Pod2HTML is used by default.
ignore
This attribute allows to ignore some input files that would be otherwise converted to HTML. Its value is a file name that should be ignored (relative to the distribution root directory). By default no (appropriate) files are ignored. The attribute can be repeated if you wish to ignore more files. For example:
[LocalHTML] ignore = lib/My/Sample.pm ignore = bin/obscure-script
is_interesting_file
The method decides (by returning something or undef) whether the given file should be a candidate for the conversion to the HTML. The parameter is a blessed object with the Dist::Zilla::Role::File role.
Dist::Zilla::Role::File
setup_installer
The main job
base_filename( $file )
Returns base name of HTML file formed of source file path. Rules are:
The result gets appenede with .html
output_filename( $file )
Create and return a suitable name for the output file for the given input $file.
pod2html( $file )
This method does the conversion to the HTML (using module defined by pod2html_class). It gets an input file (a blessed object with the Dist::Zilla::Role::File role) and it should return a converted content. By overwriting this method a new plugin can make any conversion, to anything.
get_css_style()
It returns a string containing CSS-style definitions. The string will be used in the head section of the created HTML file. See its default value in the __DATA__ section of this module.
head
This plugin is a rewrite of Dist::Zilla::Plugin::Pod2Html. I would like to express my deepest gratitude to Martin Senger <martin.senger@gmail.com> for his great work! The original copyright for Dist::Zilla::Plugin::Pod2Html follows.
This software is copyright (c) 2013 by Martin Senger, CBRC - KAUST (Computational Biology Research Center - King Abdullah University of Science and Technology) All Rights Reserved..
Vadim Belman <vrurg@cpan.org>
This software is copyright (c) 2017 by Vadim Belman.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Dist::Zilla::Plugin::LocalHTML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dist::Zilla::Plugin::LocalHTML
CPAN shell
perl -MCPAN -e shell install Dist::Zilla::Plugin::LocalHTML
For more information on module installation, please visit the detailed CPAN module installation guide.