Open Stack

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.

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?