Open Stack

Hi Anne,

On 5 August 2013 15:15, Anne Gentle <annegentle at justwriteclick.com> wrote:
> On Mon, Aug 5, 2013 at 8:55 AM, John Garbutt <john at johngarbutt.com> wrote:
>>
>> Given we seem to be leaning towards WSME:
>> http://lists.openstack.org/pipermail/openstack-dev/2013-August/012954.html
>>
>> Could we not try to make WSME give us the documentation we need?
>>
>> Not sure if its feasible, but it seems like there is a good start to
>> that already available:
>> https://wsme.readthedocs.org/en/latest/document.html
>>
> John, this looks interesting, but I have reservations. Do you know if you
> can suppress the SOAP and ExtDirect entries?

Sorry no idea, but we certainly would have to.

> Also we already have available the current way to create API docs for
> http://api.openstack.org/api-ref.html.
>
> I'm not excited about an inconsistent user experience for reading REST API
> docs for one project but not others. Where will it be published? How will
> readers find it? And so on. It's good for Compute to lead the way and try
> things, but I'd like to know if other projects are willing to follow?
> Looking for input from other projects.

Sorry I was not very clear. I certainly agree with your concerns.

My main concern would be adding a lot of documentation and lots of
validation, and them not being in sync.

We may need to create our own doc generator, and it might only be
loosely based on what they already have upstream for WSME.

Thinking about this a little more, we might want to use their
generator to create info required for the current inputs to the API
doc generation.

However, really just wondering if someone has tried this out for real?
Does it seem feasible?

John