=head1 NAME

Web::DataService::Documentation - how to write documentation templates
for Web::DataService

=head1 SYNOPSIS

This file explains the process of creating documentation templates for a
Web::DataService application.

=head1 OVERVIEW

The documentation templates for a Web::DataService application are located by
default in the F<doc> directory.  For now, the only template engine compatible
with Web::DataService is L<Template-Toolkit|Template>, but this may change in
the future.

You can create an individual documentation page for each node, by simply
creating a file in the F<doc> directory whose path corresponds the node path.
For example, the template corresponding to C<formats/json> is
F<formats/json_doc.tt>.  The template corresponding to C<formats> is
F<formats/index.tt>.  If such a file is not found, then Web::DataService will
try to use one of the common templates.  For an operation node, it will try
the value of the node attribute C<doc_default_op_template>.  For all other
nodes, it will try the value of the node attribute C<doc_default_template>.

If the node attributes C<doc_header> and C<doc_footer> are defined (as they
are by default) then the templates named by these attributes are included as a
header and footer respectively.  The default values are C<doc_header.tt> and
C<doc_footer.tt>.  The file C<doc_defs.tt> is included before every template,
to define all of the elements described below.  It includes the file
C<doc_strings.tt>, which you are free to edit in any way you choose.

=head2 Documentation format

The main format for Web::DataService documentation pages is L<Pod|perlpod>.
All documentation is generated first in Pod format, and is then converted to
HTML by the module L<Web::DataService::PodParser>.  If you want to see the
actual Pod output, you can get it via URLs like the following:

    http://localhost:3000/data1.0/index.pod
    http://localhost:3000/data1.0/list_doc.pod

You can include arbitrary Pod commands and formatting codes in both
documentation strings and template files.

=head2 Embedded links

The Web::DataService framework provides an easy way to include links from one
documentation page to another, as well as from a documentation page to an
operation (i.e. as a usage example).  This is done by using one of the
following special prefixes.  Any link specified with LE<lt>E<gt> is checked to see if
it starts with one of them, and if so then it is replaced by an auto-generated
URL which includes the appropriate path prefix, selector key, format
specifier, etc. for this data service instance.  The examples given below are
for the example application:

=over

=item node:

When a link is encountered with this prefix, the remainder is taken to be a
node path.  This is used to auto-generate a URL that will retrieve the
documentation page for that node.  For example:

    L<special parameters|node:special>
    L<JSON format|node:formats/json>

=item op:

When a link is encountered with this prefix, the remainder is parsed to
determine a node path, format, and optional parameters.  These are then used
to auto-generate a URL that will carry out the specified operation.  For
example:

    L<single.json?state=WI>
    L<regions.txt>

=item path:

When a link is encountered with this prefix, the remainder is used to
auto-generate a URL that will fetch the specified file from a file node.  For
example:

    L<css/dsdoc.css>

=back

In this way, you can specify embedded links without worrying about the details
of path prefix, data service features, etc.  In fact, you can change these
later and the documentation pages will automatically adjust!

=head1 ELEMENTS

The following elements are available for use in documentation templates.
These are all defined in the file F<doc/doc_defs.tt>.

Most of these elements generate headers corresponding to the element name, but
you can modify these by editing C<section_label> in F<doc/doc_defs.tt>.  Most
of them also generate an introductory paragraph, which you can modify by
editing the appropriate entry in C<message>.  You can also use the WRAPPER
function of Template Toolkit to override this paragraph, in the following manner:

    <% WRAPPER PARAMETERS(special) %>
    You can use any of the following special parameters with any request:
    <% END %>

=head2 NAVTRAIL

This element is replaced by a "navigation trail" linking to each level of the
node hierarchy above the currnet node.  This is typically included in a header
file, as follows:

    <% NAVTRAIL %>

=head2 DOCSTRING

This element is replaced by the value of the C<doc_string> attribute of the
data service node corresponding to this page.  You can most easily set this by
including L<documentation strings|Web::DataService::Configuration/SYNTAX> in
your calls to C<define_node>.  Use this as follows:

    <% DOCSTRING %>

=head2 USAGE

If the 'usage' attribute has been specified for this operation node, then this
element is replaced by a list of links generated from the contents of that
attribute.  Otherwise, it is ignored.  Use this as follows:

    <% USAGE %>

Or, if you don't want a separate header for this section, use the following:

    <% INCLUDE USAGE opt_noheader=1 %>

=head2 PARAMETERS

This element takes a single argument.  It is replaced by a list of the
parameters accepted by the ruleset named by the argument, along with a brief
description of each parameter.

When used in the documentation page for an operation node, you can leave out
the argument.  In that case, the ruleset corresponding to the operation node
will be used by default.

Use it as follows:

    <% PARAMETERS(ruleset_name) %>

or, in an operation documentation page, simply:

    <% PARAMETERS %>

=head2 METHODS

This element is replaced by a list of the accepted HTTP methods.  The list of
accepted methods may vary from node to node, depending upon how you use the
node attribute C<allow_method>.  Use it as follows:

    <% METHODS %>

=head2 RESPONSE

This element is only valid in documentation templates for operation nodes.  It
is replaced by a list of the data fields that are generated by this operation,
including those in the optional output blocks.  The listing for each data
field includes a brief description.  If multiple vocabularies are available,
then the name of each field in each vocabulary will be reported.

=head2 FORMATS

This element is a replaced by a list of the data formats that are provided by
the data service and allowed for this node.  This list may vary from node to node,
depending upon how you use the node attribute C<allow_format>.  You may follow
the element name with one or both of the following options:

=over

=item opt_extended=1

Include the documentation string for each format.  Without this option, the
list includes just the format name and suffix and a link to its documentation
page.

=item opt_all=1

List all formats, not just those available for this node.

=back

Use it as follows:

    <% FORMATS %>

or:

    <% INCLUDE FORMATS opt_extended=1 opt_all=1 %>

=head2 VOCABULARIES

This element is replaced by a list of the vocabularies that are provided by
the data service and allowed for this node.  This list may vary from node to
node, depending upon how you use the node attribute C<allow_vocab>.  You may
follow the element name with one or both of the following options: 

=over

=item opt_extended=1

Include the documentation string for each vocabulary.  Without this option, the
list includes just the format name and suffix and a link to its documentation
page.

=item opt_all=1

List all vocabularies, not just those available for this node.

=back

Use it as follows:

    <% VOCABULARIES %>

or:

    <% INCLUDE VOCABULARIES opt_extended=1 opt_all=1 %>



=head1 AUTHOR

mmcclenn "at" cpan.org

=head1 BUGS

Please report any bugs or feature requests to C<bug-web-dataservice at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Web-DataService>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 COPYRIGHT & LICENSE

Copyright 2014 Michael McClennen, all rights reserved.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

