The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Web-DataService-0.42
River stage zero No dependents
++
/ Web::DataService::Documentation

NAME

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

SYNOPSIS

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

OVERVIEW

The documentation templates for a Web::DataService application are located by default in the doc directory. If you wish to specify a different directory, you can do so by means of the attribute doc_template_dir. For now, the only template engine compatible with Web::DataService is Template-Toolkit, but this may change in the future.

You can create an individual documentation page for any node, by simply creating a file in the doc directory whose path corresponds the node path. There are two ways to name this file. At your option, you can either append the string _doc.tt to the node path, or you can append /index.tt. In the example application, the template corresponding to formats is formats/index.tt, but it could instead have been called formats_doc.tt. The template corresponding to formats/json is formats/json_doc.tt, but it could also have been called formats/json/index.tt. If no matching template file is not found, then Web::DataService will try to use one of the default templates. For an operation node, it will try the value of the node attribute doc_default_op_template. For all other nodes, it will try the value of the node attribute doc_default_template.

If the node attributes doc_header and 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 doc_header.tt and doc_footer.tt. The file doc_defs.tt is included before every template, to define all of the elements described below. It in turn includes the file doc_strings.tt, which you are free to edit in any way you choose.

Documentation format

The main format for Web::DataService documentation pages is Pod. All documentation is generated first in Pod format, and is then converted to HTML by the module Web::DataService::PodParser. If you want to see the actual Pod output, just replace .html with .pod at the end of a request URL. For example:

    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.

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 L<> is checked to see if it starts with one of these, 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 from the example application:

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>
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<op:single.json?state=WI>
    L<the list of regions|op:regions.txt>
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<stylesheet|path:css/dsdoc.css>

The remainder of the link is parsed as follows:

  • Everything up to the first '?' or '#' is interpreted as a node path. If it ends in '.something', that suffix is removed and interpreted as a format (except with the path: prefix).

  • If the link ends in '#something', this is removed and then appended to the end of the generated URL.

  • If the link includes a '?', everything after it is interpreted as a parameter string. Additional parameters might be automatically added, depending on which data service features are active.

The syntax described here is fixed, but the resulting URL is generated according to the particular data service features and special parameters that are active. So it might, for example, contain a format parameter if that special parameter is active and if the feature format_suffix is disabled. 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 generated URLs will automatically adjust!

Embedded html

You may embed HTML into your documentation templates by using the Pod commands =begin html, =end html, and =for html. Any content specified using these commands will be output as-is when documentation pages are generated in HTML format, whereas most Pod translators will simply ignore this content. If you wish to include data service URLs in this content, use the "URL" in URL element.

For example, if you wish to put an image on one of your documentation pages, you could do it as follows:

    =for html <img src="http://somewhere.org/some/image.gif">

If you wish to make an image available via your data service and also display it on a page, try the following:

    =for html <img src="<% URL('path:images/my_image.gif') %>">

In order for this to work you would also need to define a data service node with path "images" and a "file_dir" attribute that points to the directory on disk where f<my_image.gif> is located.

ELEMENTS

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

If you wish to change the names of the section headers, you can edit the variable section_label in doc/doc_defs.tt. If you wish to change the contents of the introductory paragraph of each section, you can edit the appropriate entry in the variable message. Alternatively, you can 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 %>

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 %>

DESCRIPTION_SECTION

If the doc_string attribute has been set for the node corresponding to this page, then this element is replaced by the default heading "DESCRIPTION", followed by the doc_string value. You can most easily set this by including documentation strings in your calls to define_node.

If no doc_string value was given for this node, then this element will be ignored unless the option opt_force=1 is given. You can use either of the following calls:

    <% DESCRIPTION_SECTION %>
    <% DESCRIPTION_SECTION(opt_force=1) %>

DOCSTRING

This element is replaced by the value of the doc_string attribute of the node corresponding to this page, with no header. Use it as follows:

    <% DOCSTRING %>

USAGE_SECTION

If the usage attribute has been specified for the node corresponding to this page, then this element is replaced by the default heading "USAGE" followed by a list of links generated from the contents of that attribute. Otherwise, it is ignored. Use this as follows:

    <% USAGE_SECTION %>

USAGE

This element is simply replaced by the list of usage links, or ignored if none have been specified. Use it as follows:

    <% USAGE %>

NODELIST

This element is replaced by a list of nodes that are children of the current one. The list will include: the node title, the node description, and the node usage. Only nodes for which the attribute place was given a nonzero value will be included. Use it as follows:

    <% SUBNODES %>

PARAMETER_SECTION

This element is replaced by the default header "PARAMETERS" followed by a list of the parameters accepted by node corresponding to this page, along with a brief description of each parameter. If you wish to document the parameters accepted by a different ruleset, include the ruleset name as a parameter. Use it in one of the following ways:

    <% PARAMETER_SECTION %>
    <% PARAMETER_SECTION(ruleset_name) %>

PARAMETERS

This element is simply replaced by the parameter documentation for the node corresponding to this page, with no header. If you wish to document the parameters accepted by a different ruleset, include the ruleset name as a parameter. Use it in one of the following ways:

    <% PARAMETERS %>
    <% PARAMETERS(ruleset_name) %>

METHOD_SECTION

This element is replaced by the default header "METHODS" followed by a list of the HTTP methods accepted by the node corresponding to this page. The list of accepted methods may vary from node to node, depending upon how you set the node attribute allow_method. Use it as follows:

    <% METHOD_SECTION %>

METHODS

This element is simply replaced by the list of methods accepted by the node corresponding to this page, with no header. Use it as follows:

    <% METHODS %>

RESPONSE_SECTION

This element is only valid in documentation templates for operation nodes. It is replaced by the default header "RESPONSE" followed 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. Use it as follows:

    <% RESPONSE_SECTION %>

RESPONSE

This element is simply replaced by the response documentation for the node corresponding to this page, with no header. Use it as follows:

    <% RESPONSE %>

FORMAT_SECTION

This element is a replaced by the default header "FORMATS" followed 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 allow_format. You may follow the element name with one or both of the following options:

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.

opt_all=1

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

Use it in one of the following ways:

    <% FORMAT_SECTION %>
    <% FORMAT_SECTION(opt_extended=1,opt_all=1) %>

FORMATS

This element is simply replaced by the format documentation for the node corresponding to this page, with no header. The same options are available as with FORMAT_SECTION. Use it as follows:

    <% FORMATS %>

VOCAB_SECTION

This element is replaced by the default header "VOCABULARIES" followed 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 allow_vocab. You may follow the element name with one or both of the following options:

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.

opt_all=1

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

Use it in one of the following ways:

    <% VOCAB_SECTION %>
    <% VOCAB_SECTION(opt_extended=1,opt_all=1) %>

VOCABS

This element is simply replaced by the vocabulary documentation for the node corresponding to this page, with no header. The same options are available as with VOCAB_SECTION. Use it as follows:

    <% VOCABS %>

URL

This element is used to generate arbitrary URLs in accordance with the data service features and special parameters that are currently active. See Embedded links above for a description of the syntax. You will probably only need to use this element if you include "Embedded html" in embedded html in your templates. In the rest of your documentation you can just enclose any URLs in L<> and they will be automatically translated. For example, you could put something like the following in f<doc_header.tt>:

    =begin html
    <div class="banner">
        <img id="logo" src="<% URL('path:images/my_logo.png') %>">
        <h1 id="title">My Data Service: <% doc_title %></h1>
    </div>
    =end html

In order for this to work you would also need to define a data service node with path "images" and a "file_dir" attribute that points to the directory on disk where f<my_logo.png> is located.

AUTHOR

mmcclenn "at" cpan.org

BUGS

Please report any bugs or feature requests to bug-web-dataservice at rt.cpan.org, or through the web interface at 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.

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.