NAME Pod::Weaver::Plugin::Rinci - Insert stuffs to POD from Rinci metadata VERSION This document describes version 0.785 of Pod::Weaver::Plugin::Rinci (from Perl distribution Pod-Weaver-Plugin-Rinci), released on 2023-03-02. 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. PERL_POD_WEAVER_PLUGIN_RINCI_EXCLUDE_FILES String (regex pattern). Used to set the default value for the "/exclude_files" configuration option. HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . SEE ALSO Pod::Weaver AUTHOR perlancar CONTRIBUTOR Steven Haryanto 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, 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. COPYRIGHT AND LICENSE This software is copyright (c) 2023, 2022, 2019, 2017, 2016, 2015, 2014, 2013, 2012, 2011 by perlancar . 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 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.