[openstack-dev] [Openstack-docs] [Heat][Documentation] Heat template documentation

Gauvain Pocentek gauvain.pocentek at objectif-libre.com
Wed May 28 05:17:41 UTC 2014


Le 2014-05-28 03:04, Steve Baker a écrit :
> On 28/05/14 03:15, Gauvain Pocentek wrote:
>> Le 2014-05-23 15:57, Anne Gentle a écrit :
>>> On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at redhat.com> 
>>> wrote:
>>> 
>>>> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote:
>>>>> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <shardy at redhat.com>
>>>>> wrote:
>>>>> 
>>>>>> On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote:
>>>>>>> On 05/23/2014 12:13 PM, Steven Hardy wrote:
>>>>>>>> [...]
>>>>>>>> I'll hold my hand up as one developer who tried to contribute
>>>>>>>> but ran
>>>>>> away
>>>>>>>> screaming due to all the XML-java-ness of the current process.
>>>>>>>> I don't think markup complexity is a major barrier to 
>>>>>>>> contribution.
>>>>>> Needing
>>>>>>>> to use a closed source editor and download unfathomably huge
>>>>>>>> amounts of
>>>>>>>> java to build locally definitely are though IMO/IME.
>>>>>>> You do not need a closed sourced editor for XML - I'm using 
>>>>>>> emacs
>>>>>>> and
>>>>>>> others in the team use vi for it.
>>>>>> Sure, maybe "need" was the wrong word to use, my apologies.
>>>>>>  Regardless,
>>>>>> the docs refer to a closed source tool being "encouraged", which
>>>>>> immediately discouraged me when trying to figure out the 
>>>>>> workflow.
>>>>>> I've tried editing XML in vim a few times, and although it's
>>>>>> obviously
>>>>>> possible, it's far less painful when I'm dealing with other more
>>>>>> human-friendly formats.
>>>>>> 
>>>>>>> Yes, it downloads a lot Java once. We also now build the
>>>>>>> documents as
>>>>>>> part of the gate, so you can also check changes by clicking the
>>>>>>> "checkbuild" target, it will show you the converted books,
>>>>>> Sure, that's good, but my (and I'd guess many others) preference
>>>>>> is for
>>>>>> formats which can be easily built locally with only
>>>>>> distro-provided tools,
>>>>>> not a huge pile of third party java.
>>>>>> Not trying to start a format-advocacy argument here, just trying
>>>>>> to provide
>>>>>> a data-point that, if the success criteria is developer
>>>>>> participation in
>>>>>> the docs process, then the current toolchain is definitely a
>>>>>> barrier to
>>>>>> participation for some potential contributors.
>>>>>> 
>>>>> 
>>>>> Thanks for the discussions -- let's keep a tone of civility.
>>>>> Understand
>>>>> that doc writers have specific tools that work well for them. That
>>>>> said, we
>>>>> do want to collaborate more with our end users specifically.
>>>> My apologies if my remarks have been interpreted as uncivil, that 
>>>> was
>>>> definitely not my intention.
>>> Oh no not at all, sorry -- my intent is that we are all staying 
>>> civil
>>> and it's good. :)
>>> 
>>> 
>>>> The only point I really wanted to convey was +1 on trying out an 
>>>> easier
>>>> markup, and thanks for bringing up the topic of a user orientated
>>>> orchestration guide - I would definitely like to contribute to the
>>>> effort.
>>> So we're still a little stuck on the tradeoffs -- with easier markup
>>> we lose some features.
>>> For other generated reference docs, we maintain a set of python
>>> scripts in openstack-doc-tools. Is it possible for someone to look
>>> into generating the Heat template reference information outside of
>>> Sphinx?
>> 
>> Yes, I can look into that.
>> 
>> The idea would be to generate some docbook from RST... So why not do
>> it for the whole to-be-written heat user guide in that case?
>> 
>> What I get from this thread is that 1) docbook is the best format to
>> use to generate a nice and feature-rich output, 2) developers don't
>> want to write docbook. Without being able to handle a different 
>> format
>> developers will no contribute, which is bad because they want, and we
>> want them to contribute :)
>> 
>> So my feeling is that we should work on the tools to convert RST (or
>> whatever format, but RST seems to be the "norm" for openstack
>> projects) to docbook, and generate our online documentation from
>> there. There are tools that can help us doing that, and I don't see 
>> an
>> other solution that would make us move forward.
>> 
>> Anne, you talked about experimenting with the end user guide, and
>> after the discussion and the technical info brought by Doug, Steve 
>> and
>> Steven, I now think it is worth trying.
>> 
> In this vein, I enabled the sphinx xml builder in heat:
> https://review.openstack.org/#/c/95979/
> 
> And here is a sample of the output:
> http://paste.openstack.org/show/81811/
> http://paste.openstack.org/show/81812/
> 
> This looks like it could be readily transformed into DocBook via XSL.

http://ebellot.chez.com/dn2dbk/index.htm could be used as a starting 
point. It generates docbook 4, but can probably be easily modified to 
generate docbook 5, adapted to our conventions. The doc is in french, if 
anyone's interested I can do a quick translation of the important parts.

> Alternatively we could write a Docutils writer which writes docbook
> directly, possibly using this as a starting point:
> http://docutils.sourceforge.net/sandbox/oliverr/docbook/
> 
> Any takers to start playing with this?

I need to dive into docutils writers to understand/maintain an internal 
tool of ours, so /me volunteers.

I also looked at how pandoc handles the RST -> docbook conversion, but 
I don't think it's not good enough for our needs.

I'll play with these tools this week to see which one is the best 
option for us.

Thanks!
Gauvain



More information about the OpenStack-dev mailing list