NAME

Parrot::Docs::Item - Docmentation item

SYNOPSIS

use Parrot::Docs::Item;

my $item = Parrot::Docs::Item->new('Usual suspects', 'foo', 'bar');

DESCRIPTION

An item is one or more related paths with some optional descriptive text.

Directory paths will be expanded to all the file paths within the directory and any subdirectories recursively (see the files() method in Parrot::IO::Directory).

If an item has more than one file associated with it, and has no text, then an attempt will be made to extract short descriptions from each file to place under the file path in the index HTML.

Methods

new_item($text, @paths)

Returns a new item.

Use this when creating items in a section's new() method.

new($text, @contents)

Returns a new item. If there is no descriptive text then $text should be an empty string.

The paths in @contents will be interpreted as being relative to the $target argument in write_html(). There should be at least one path otherwise an exception is raised.

set_parent($parent)

parent()

Accessors for the containing section/group for the item.

html_navigation($path)

Returns the HTML navigation bar.

write_html($source, $target, $silent)

Any POD-formatted text in the item's files is converted to HTML and written to a file in $target and an HTML link is created to it.

Alternatively, if a file responds true to is_docs_link() then an HTML link is created to the file itself.

Some HTML-formatted text describing the files linked to is returned.

contents_relative_to_source($source)

Returns the contents of the item interpreted relative to the source directory.

file_paths_relative_to_source($source, $path)

If $path is an immediate subdirectory of $source, then this method returns all the file paths within the directory and any subdirectories recursively, relative to $source.

If $path is a file in $source then $path is returned.

If $path cannot be found then a warning is printed.

SEE ALSO

Parrot::Docs::Section, Parrot::Docs::Group.