Open Stack

Hi,

Thanks everyone for the feedback.

More inline...

Le 2014-07-17 15:18, Anne Gentle a écrit :
> On Wed, Jul 16, 2014 at 2:13 PM, Gauvain Pocentek
> <gauvain.pocentek at objectif-libre.com> wrote:
> 
>> Hi all,
>> 
>> We discussed how to add a HOT template guide ([bp]) off list and we'd 
>> like to have some feedback before getting really started.
>> 
>> So what we plan to do is:
>> 
>> - Write the guide in RST and generate a docbook chapter (the tool to 
>> do so is almost ready) that will be included in the user guide. We 
>> really think this is the way to go, because we want to make things 
>> easier for developers to contribute. So unless there are strong 
>> feelings against this, we'll probably get started soon.
> 
> I'm okay with this, but will say in my experience rst to docbook is
> fiddly and you only want to do it once, it's not automatable. (I know
> you're not talking about repeated imports, just one time.)

I'm quite confident that we will be able to do multiple imports 
actually. But we won't be able to merge back changes from docbook to the 
source RST. In case I'm completely wrong, we'll have the possibility to 
do a one-time import anyway, and then work on the docbook source.

> 
> One thing I noted is that there is already an RST guide, but I've
> gotten feedback that it's too simple of an example and we'll want to
> add a more real-world example. So I'd say start with the RST files
> that exists
> at http://git.openstack.org/cgit/openstack/heat/tree/doc/source/template_guide
> [3] and go from there.

Sounds good. I'll pick whatever can be picked in there and create an 
initial sphinx space in our manuals repo.

>  
> 
>> - We (I?)'d like to include the HOT reference ([ref]) in the manuals, 
>> but we're not sure where we should include it. Including it in the 
>> user guide would probably clutter this guide, the CLI and config 
>> references don't look like good candidates either, and another guide 
>> just for this is probably overkill. A last solution is to keep the 
>> (unversioned) reference in the developer/ namespace.
>> What do you guys think about this?
> 
> I think that the HOT Reference can be a separate guide like the CLI
> Ref and Config Ref. It's not a lot of overhead since it's
> automatically generated.

Great!

Gauvain



> 
>  Anne
>   Thanks,
>  G
> 
>> penstack-manuals/+spec/heat-templates)
>> [ref]: http://docs.openstack.org/developer/heat/template_guide/ [1]
>> 
>> _______________________________________________
>> Openstack-docs mailing list
>> Openstack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs 
>> [2]
> 
> 
> Links:
> ------
> [1] http://docs.openstack.org/developer/heat/template_guide/
> [2] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> [3] 
> http://git.openstack.org/cgit/openstack/heat/tree/doc/source/template_guide