Open Stack

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 <tengqim at linux.vnet.ibm.com> wrote on 14/02/2014 06:55:56:
>>
>>> From: Qiming Teng <tengqim at linux.vnet.ibm.com>
>>> To: openstack-dev at 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: tengqim at cn.ibm.com
>>>
>>>
>>> _______________________________________________
>>> OpenStack-dev mailing list
>>> OpenStack-dev at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>