Open Stack

Le 2014-05-28 07:17, Gauvain Pocentek a écrit :
> 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.

The result of my tests: 
http://pocentek.net/~gauvain/heat-template-guide/content/

I used the XML generated by 'sphinx-build xml' as source, with this 
resources.py patch: https://review.openstack.org/96398

There are a few things manually setup (pom.xml, and the master 
structure of the docbook XML), but I think that they could be automated. 
I also used a few sed commands, mainly to handle xml IDs. It might be 
possible to handle this with xslt, but using sed was a faster solution.

You can get the code: git clone 
http://pocentek.net/~gauvain/heat-template-guide/poc-rst2docbook

There's room for improvement, and we should test more advanced RST 
markup, but I think that this solution could really work for the user 
guide.

Gauvain