Documentation/blueprints/heat-templates


 * Launchpad Entry: Add documentation about heat templates

Overview
The documentation about how to write heat templates in the openstack-manuals repository is almost nonexistent. This specification describes the steps needed to include existing documentation (developer reference) in the repository, and which additional documentation should be written to improve the user experience when using heat.

Audience for the heat template documentation
The template documentation will be consumed by end users of the Orchestration Module (heat). It will be added to the user-guide, as new chapters.

Source language
To ease the developers contributions to this documentation, the RST language will be used as source.

A tool will handle the RST to docbook translation. The docbook output will be included in the manuals repository (manually or automatically) to generate the published documentation (HTML and PDF).

Getting started section
A "Getting Started" section will provide the user with a detailed documentation on how to write templates. It will cover the basic aspects of the templates:
 * architecture, format and languages
 * resources definition
 * parameters definition
 * usage of functions and attributes
 * links between resources

This section will cover the base resources: nova server, neutron nets, subnets and ports, cinder volumes...

Details about more complex resources
This section will document how to use more complex resources such as:
 * WaitConditions
 * HA and alarming
 * AutoScaling

Inclusion of the heat template reference
The heat repository provides detailed documentation about resources, parameters and functions that can be used to write templates. This documentation will be integrated in the user-guide.

The heat documentation is written in RST, and most of its content is generated from the source code with sphinx. The output cannot be used as is in the openstack-manuals repository. A first step will be to write a tool to translate the sphinx generated documentation to docbook. The generated docbook XML will be included in the user-guide, probably manually at first, and will be automated, if possible.

rst2OSdocbook
Some implementation details fot the RST to docbook translator:
 * source data will be the native docutils XML as generated by sphinx
 * xslt will be used to transform the source XML, with the help of custom python code