Open Stack

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