/ 
Pod-Weaver-Plugin-Rinci-0.781
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.781 of Pod::Weaver::Plugin::Rinci (from Perl distribution Pod-Weaver-Plugin-Rinci), released on 2022-06-13.

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.

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.