Open Stack

On 02/05/2015 07:26 PM, Michael Krotscheck wrote:
> On Thu Feb 05 2015 at 12:07:01 AM Radomir Dopieralski
> <openstack at sheep.art.pl <mailto:openstack at sheep.art.pl>> wrote:
> 
> 
>     Plus, the documentation generator that we are using already, Sphinx,
>     supports JavaScript perfectly fine, so I see no reason to add
>     another tool.
> 
> 
> Try to empathize with us a little here. What you're asking is equivalent
> to saying "OpenStack should use JavaDoc for all its documentation
> because it supports python". For all the reasons that you would mistrust
> JavaDoc, I mistrust Sphinx when it comes to parsing javascript.
> 
> With that in mind, how about we run a side-by-side comparison of Sphinx
> vs. NGDoc? Without actual comparable output, this discussion isn't much
> more than warring opinions.

I'm not mistrusting JavaDoc or NGDoc or whatever new documentation
system you are proposing. I merely think that, while JavaScript
programmers are special snowflakes indeed, they are not special enough
warrant introducing and maintaining a whole separate documentation
system, especially since we are already using a documentation system
that is well used and maintained by the whole of OpenStack, not just the
Python programmers in Horizon. And since you will have to learn to use
Sphinx sooner or later anyways, because basically everything in
OpenStack is documented using it, I see no reason why we should expend
additional energy on implementing, deploying and maintaining a new set
of tools, just because you don't like the current one.

If it was JavaDoc instead of Sphinx being used by the whole of
OpenStack, I would advocate its use the same way as I advocate Sphinx now.

It seems that the whole docs format discussion is just a way of putting
away having to actually write the docs.

-- 
Radomir Dopieralski