NAME

       App::DocKnot::Generate - Generate documentation from package metadata

SYNOPSIS

           use App::DocKnot::Generate;
           my $docknot
             = App::DocKnot::Generate->new({ metadata => 'docs/docknot.yaml' });
           my $readme = $docknot->generate('readme');
           my $index = $docknot->generate('thread');
           $docknot->generate_output('readme');
           $docknot->generate_output('thread', 'www/index.th')

REQUIREMENTS

       Perl 5.24 or later and the modules File::BaseDir, File::ShareDir, Kwalify, Path::Tiny,
       Template (part of Template Toolkit), and YAML::XS, all of which are available from CPAN.

DESCRIPTION

       This component of DocKnot provides a system for generating consistent human-readable
       software package documentation from metadata files, primarily JSON and files containing
       documentation snippets.  It takes as input a directory of metadata and a set of templates
       and generates a documentation file from the metadata given the template name.

       The path to the metadata directory for a package is given as an explicit argument to the
       App::DocKnot::Generate constructor.  All other data (currently templates and license
       information) is loaded via File::BaseDir and therefore uses XDG paths by default.  This
       means that templates and other global configuration are found by searching the following
       paths in order:

       1.  $HOME/.config/docknot

       2.  $XDG_CONFIG_DIRS/docknot (/etc/xdg/docknot by default)

       3.  Files included in the package.

       Default templates and license files are included with the App::DocKnot module and are used
       unless more specific configuration files exist.

CLASS METHODS

       new(ARGS)
           Create a new App::DocKnot::Generate object.  This should be used for all subsequent
           actions.  ARGS should be a hash reference with one or more of the following keys:

           metadata
               The path to the directory containing metadata for a package.  Default:
               docs/docknot.yaml relative to the current directory.

           width
               The wrap width to use when generating documentation.  Default: 74.

INSTANCE METHODS

       generate(TEMPLATE)
           Load the metadata from the path given in the constructor and generate the
           documentation file defined by TEMPLATE, which is the name of a template.  The template
           itself will be loaded from the App::DocKnot configuration path as described in
           DESCRIPTION.  Returns the generated documentation file as a string.

       generate_all()
           Generate all of the documentation files for a package.  This is currently defined as
           the "readme" and "readme-md" templates.  The output will be written to the default
           output locations, as described under generate_output().

       generate_output(TEMPLATE [, OUTPUT])
           The same as generate() except that rather than returning the generated documentation
           file as a string, it will be written to the file named by OUTPUT.  If that argument
           isn't given, a default based on the TEMPLATE argument is chosen as follows:

               readme     ->  README
               readme-md  ->  README.md

           If TEMPLATE isn't one of the templates listed above, the OUTPUT argument is required.

AUTHOR

       Russ Allbery <rra@cpan.org>

COPYRIGHT AND LICENSE

       Copyright 2013-2022 Russ Allbery <rra@cpan.org>

       Permission is hereby granted, free of charge, to any person obtaining a copy of this
       software and associated documentation files (the "Software"), to deal in the Software
       without restriction, including without limitation the rights to use, copy, modify, merge,
       publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
       to whom the Software is furnished to do so, subject to the following conditions:

       The above copyright notice and this permission notice shall be included in all copies or
       substantial portions of the Software.

       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
       INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
       PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
       FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
       OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
       DEALINGS IN THE SOFTWARE.

SEE ALSO

       docknot(1), App::DocKnot::Config

       This module is part of the App-DocKnot distribution.  The current version of DocKnot is
       available from CPAN, or directly from its web site at
       <https://www.eyrie.org/~eagle/software/docknot/>.