Pod::Weaver::Plugin::Rinci - Insert stuffs to POD from Rinci metadata
This document describes version 0.786 of Pod::Weaver::Plugin::Rinci (from Perl distribution Pod-Weaver-Plugin-Rinci), released on 2023-04-14.
In your weaver.ini:
[-Rinci] ;exclude_modules = REGEX ;exclude_files = REGEX
This plugin inserts stuffs to POD documentation based on information found on Rinci metadata.
For modules, the following are inserted:
DESCRIPTION
From description property from package metadata, if any.
description
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 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.
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.
run()
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.
subcommands
To exclude a script from being processed, you can also put # NO_PWP_RINCI in the script.
# NO_PWP_RINCI
String, a regex.
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.
@Filter
PERL_POD_WEAVER_PLUGIN_RINCI_USE_REQUIRE_HOOK_SOURCE_DZILBUILD
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.
PERL_POD_WEAVER_PLUGIN_RINCI_FORCE_RELOAD
Bool. Used to set the default for the /use_require_hook_source_dzilbuild configuration option.
/use_require_hook_source_dzilbuild
Bool. Used to set the default for the /force_reload configuration option.
/force_reload
String (regex pattern). Used to set the default value for the /exclude_modules configuration option.
/exclude_modules
By default, if this is not specified, then some modules are by default skipped:
'\\A(Sah::SchemaR::.+|Pod::Weaver::Plugin::Rinci)\\z'
String (regex pattern). Used to set the default value for the /exclude_files configuration option.
/exclude_files
Please visit the project's homepage at https://metacpan.org/release/Pod-Weaver-Plugin-Rinci.
Source repository is at https://github.com/perlancar/perl-Pod-Weaver-Plugin-Rinci.
Pod::Weaver
perlancar <perlancar@cpan.org>
Steven Haryanto <stevenharyanto@gmail.com>
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, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.
This software is copyright (c) 2023, 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.
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.
To install Pod::Weaver::Plugin::Rinci, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pod::Weaver::Plugin::Rinci
CPAN shell
perl -MCPAN -e shell install Pod::Weaver::Plugin::Rinci
For more information on module installation, please visit the detailed CPAN module installation guide.