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 each 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, you can get it via URLs like the following:
http://localhost:3000/data1.0/index.pod
http://localhost:3000/data1.0/list_doc.podYou can include arbitrary Pod commands and formatting codes in both documentation strings and template files.
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 L<> 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:
- 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>
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!
ELEMENTS
The following elements are available for use in documentation templates. These are all defined in the file doc/doc_defs.tt.
Most of these elements generate headers corresponding to the element name, but you can modify these by editing section_label in doc/doc_defs.tt. Most of them also generate an introductory paragraph, which you can modify by editing the appropriate entry in 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 %>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 %>DOCSTRING
This element is replaced by the value of the doc_string attribute of the data service node corresponding to this page. You can most easily set this by including documentation strings in your calls to define_node. Use this as follows:
<% DOCSTRING %>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 %>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 %>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 set the node attribute allow_method. Use it as follows:
<% METHODS %>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.
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 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 as follows:
<% FORMATS %>or:
<% INCLUDE FORMATS opt_extended=1 opt_all=1 %>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 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 as follows:
<% VOCABULARIES %>or:
<% INCLUDE VOCABULARIES opt_extended=1 opt_all=1 %>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.