"new(\%params)"

Constructor. \%params is optional. If present, the following keys are valid:

"callbacks"

See documentation below for "convert_file()".

"namespace"

If a namespace is declared then links to that namespace are converted to cross references and an anchor is added for each head tag.

"convert_file($source_file, $title, $dest_file, $callbacks)"

Converts the POD in $source_file to reStructuredText. If $dest_file is defined, it writes the output there. If $title is defined, it is used for the title of the document. Otherwise, an attempt is made to infer the title from the NAME section (checks if the body looks like "/\A\s*(\w+(?:::\w+)+)\s+-\s+/s").

Returns the output as a string.

$source_file and $dest_file can be either file names or file handles.

"convert_files($file_spec, $index_file, $index_title, $out_dir)"

Converts the files given in $file_spec to reStructuredText. If $index_file is provided, it is the path to the index file to be created (with a table of contents pointing to all of the files created). If $index_title is provided, it is used as the section title for the index file. $out_dir is the directory the generated files will be written to.

$file_spec is a reference to an array of hashes specifying attributes for each file to be converted. The valid keys are:

"source_file"

File to convert.

"dest_file"

File to output the reStructuredText. If not provided, a file name will be generated based on the title.

"title"

Section title for the generated reStructuredText. If not provided, an attempt will be made to infer the title from the NAME section in the POD, if it exists. As a last resort, a title will be generated that looks like "section_(\d+)".

"callbacks"

A reference to a hash containing names and the corresponding callbacks.

Currently the only valid callback is "link". It is given the text inside a L<> section from the POD, and is expected to return a tuple "($url, $label)". If the value returned for $label is undefined, the value of $url is used as the label.

"no_toc"

Causes the item to not be printed to the index or return in the "toc" field.

This method returns a hash ref with a table of contents (the "toc" field) suitable for a reStructuredText table of contents.

E.g.,

    my $conv = Pod::POM::View::Restructured->new;
    
    my $files = [
                  { source_file => "$base_dir/Restructured.pm" },
                  { source_file => "$base_dir/DWIW.pm" },
                  { source_file => "$base_dir/Wrapper.pm" },
                 ];
    
    my $rv = $conv->convert_files($files, "$dest_dir/index.rst", 'My Big Test', $dest_dir);

=for pod2rst next-code-block: lang

This sets up the next verbatim section, i.e., the next indented paragraph to be highlighted according to the syntax of the programming/markup/config language lang. Verbatim sections are assumed to be Perl code by default. Sphinx uses Pygments to do syntax highlighting in these sections, so you can use any value for lang that Pygments supports, e.g., Python, C, C++, Javascript, SQL, etc.