NAME

Parrot::Docs::Item - Documentation item

SYNOPSIS

use Parrot::Docs::Item;

DESCRIPTION

A documentation 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.

Class Methods

new_item($text, @paths)

Returns a new item.

Use this when creating items within a Parrot::Docs::Section subclass'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.

Instance Methods

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)

$source is the directory in which the section's contents will be looked for.

$target is directory into which the section's output will be written.

If $silent is true then progress is not reported.

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