The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Pod-Weaver-Plugin-Rinci-0.784
River stage one • 2 direct dependents • 3 total dependents
++
/ Pod::Weaver::Plugin::Rinci

NAME

Pod::Weaver::Plugin::Rinci - Insert stuffs to POD from Rinci metadata

VERSION

This document describes version 0.784 of Pod::Weaver::Plugin::Rinci (from Perl distribution Pod-Weaver-Plugin-Rinci), released on 2022-07-24.

SYNOPSIS

In your weaver.ini:

 [-Rinci]
 ;exclude_modules = REGEX
 ;exclude_files = REGEX

DESCRIPTION

This plugin inserts stuffs to POD documentation based on information found on Rinci metadata.

For modules

For modules, the following are inserted:

  • DESCRIPTION

    From description property from package metadata, if any.

  • FUNCTIONS (or METHODS)

    Documentation for each function (or method) for which the metadata is found under the package will be added here. For each function, there will be summary, description, usage, list of arguments and their documentation, as well as examples, according to what's available in the function metadata of corresponding function.

To get Rinci metadata from a module, Perinci::Access::Perl is used.

For Perinci::CmdLine-based CLI script

For scripts using Perinci::CmdLine (or its variant ::Any and ::Lite), the following are inserted:

  • SYNOPSIS

    If the script's POD does not yet have this section, this section will be added containing the usage line of the script.

  • DESCRIPTION

    If the script's POD does not already have this section, and if the script does not have subcommands, description from function metadata will be inserted here, if any.

  • SUBCOMMANDS

    If the script's POD does not already have his section, and if the script has subcommands, then each subcommand will be listed here along with its summary and description.

  • OPTIONS

    If the script's POD does not already have his section, command-line options for the script will be listed here. If script has subcommands, the options will be categorized per subcommand.

  • CONFIGURATION

    If the script's POD does not already have his section, general information about configuration files and available configuration parameters will be listed here. If script has subcommands, the parameters will be categorized per subcommand.

  • FILES

    Configuration files read by script will be listed here.

To get Perinci::CmdLine object information (which contains the URL of the Rinci function, or the list of subcommands, among others), the script is run with a patched run() that will dump the content of the object and exit immediately, so the plugin can inspect it.

Caveats: 1) Function used by the script must reside in the module, not embedded inside the script itself, otherwise it will not be readable by the plugin. 2) Coderef subcommands is not supported.

To exclude a script from being processed, you can also put # NO_PWP_RINCI in the script.

CONFIGURATION

exclude_modules

String, a regex.

exclude_files

String, a regex.

use_require_hook_source_dzilbuild

Bool, default true.

Since weaver.ini does not provide something like @Filter in dist.ini, you can also use the environment variable PERL_POD_WEAVER_PLUGIN_RINCI_USE_REQUIRE_HOOK_SOURCE_DZILBUILD to set the default value of this configuration option.

force_reload

Bool, default true.

Whether to force reloading modules, to get the latest version (e.g. a module is already loaded by another plugin but then might get modified; when we are processing the module we might want to reload to get the latest version.

But this reloading sometimes causes the module to fail to compile, so this option exists.

Since weaver.ini does not provide something like @Filter in dist.ini, you can also use the environment variable PERL_POD_WEAVER_PLUGIN_RINCI_FORCE_RELOAD to set the default value of this configuration option.

ENVIRONMENT

PERL_POD_WEAVER_PLUGIN_RINCI_USE_REQUIRE_HOOK_SOURCE_DZILBUILD

Bool. Used to set the default for the /use_require_hook_source_dzilbuild configuration option.

PERL_POD_WEAVER_PLUGIN_RINCI_FORCE_RELOAD

Bool. Used to set the default for the /force_reload configuration option.

PERL_POD_WEAVER_PLUGIN_RINCI_EXCLUDE_MODULES

String (regex pattern). Used to set the default value for the /exclude_modules configuration option.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Pod-Weaver-Plugin-Rinci.

SOURCE

Source repository is at https://github.com/perlancar/perl-Pod-Weaver-Plugin-Rinci.

SEE ALSO

Pod::Weaver

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTOR

Steven Haryanto <stevenharyanto@gmail.com>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2019, 2017, 2016, 2015, 2014, 2013, 2012, 2011 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Weaver-Plugin-Rinci

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.