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 <[email protected]> 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 <[email protected]> >>>> 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? _______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
