On 14/02/14 03:21, Qiming Teng wrote:
On Fri, Feb 14, 2014 at 08:24:09AM +0100, Thomas Spatzier wrote:
Thanks, Thomas.
The first link actually provides a nice inventory of all Resources and
their properties, attributes, etc. I didn't look into this because I
was thinking of the word 'developer' differently. This pointer is
useful for template developers in the sense that they don't have to
check the source code to know a resource type.
Yeah, we are overloading the term 'developer' here, since that section
contains both information that is only useful to developers working on
Heat itself, and information useful to users developing templates.
I'm not sure if this is forced because of an OpenStack-wide assumption
that there is only API documentation and developer documentation?
We ought to split these up and make the difference clear if we can.
Maybe more elaborated explanation of resource usage is some work that
can be left to book or manual authors.
Your original suggestion was a good one - we actually already include
the docstrings from resource plugin classes when we generate the
template documentation.[1] So we just have to write docstrings for all
the resource types...
cheers,
Zane.
[1]
https://github.com/openstack/heat/blob/eae9a2ad3f5d3dcbcbb10c88a55fd81f1fe2dd56/doc/source/ext/resources.py#L47
Regards,
- Qiming
Hi Qiming,
not sure if you have already seen it, but there is some documentation
available at the following locations. If you already know it, sorry for
dup ;-)
Entry to Heat documentation:
http://docs.openstack.org/developer/heat/
Template Guide with pointers to more details like documentation of all
resources:
http://docs.openstack.org/developer/heat/template_guide/index.html
HOT template guide:
http://docs.openstack.org/developer/heat/template_guide/hot_guide.html
HOT template spec:
http://docs.openstack.org/developer/heat/template_guide/hot_spec.html
Regards,
Thomas
Qiming Teng <teng...@linux.vnet.ibm.com> wrote on 14/02/2014 06:55:56:
From: Qiming Teng <teng...@linux.vnet.ibm.com>
To: openstack-dev@lists.openstack.org
Date: 14/02/2014 07:04
Subject: [openstack-dev] [Heat] Need more sample HOT templates for users
Hi,
I have been recently trying to convince some co-workers and even some
customers to try deploy and manipulate their applications using Heat.
Here are some feedbacks I got from them, which could be noteworthy for
the Heat team, hopefully.
- No document can be found on how each Resource is supposed to be
used. This is partly solved by the adding resource_schema API but it
seems not yet exposed by heatclient thus the CLI.
In addition to this, resource schema itself may print only simple
help message in ONE sentence, which could be insufficient for users
to gain a full understanding.
- The current 'heat-templates' project provides quite some samples in
the CFN format, but not so many in HOT format. For early users,
this means either they will get more accustomed to CFN templates, or
they need to write HOT templates from scratch.
Another suggestion is also related to Resource usage. Maybe more
smaller HOT templates each focusing on teaching one or two resources
would be helpful. There could be some complex samples as show cases
as well.
Some thoughts on documenting the Resources:
- The doc can be inlined in the source file, where a developer
provides the manual of a resource when it is developed. People won't
forget to update it if the implementation is changed. A Resource can
provide a 'describe' or 'usage' or 'help' method to be inherited and
implemented by all resource types.
One problem with this is that code mixed with long help text may be
annoying for some developers. Another problem is about
internationalization.
- Another option is to create a subdirectory in the doc directory,
dedicated to resource usage. In addition to the API references, we
also provide resource references (think of the AWS CFN online docs).
Does this makes senses?
Regards,
- Qiming
---------------------------------------------
Qiming Teng, PhD.
Research Staff Member
IBM Research - China
e-mail: teng...@cn.ibm.com
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
