Open Stack

On 23/11/17 07:04, Graham Hayes wrote:
>
> On 16/11/17 01:56, Gilles Dubreuil wrote:
>> On 15/11/17 03:07, Doug Hellmann wrote:
>>> Excerpts from Gilles Dubreuil's message of 2017-11-14 10:15:02 +1100:
>>>> Hi,
>>>>
>>>> Follow-up conversation from our last "API SIG feedback and discussion
>>>> session" at Sydney Summit [1], about APIs schema consumption.
>>>>
>>>> Let's summarize the current situation.
>>>>
>>>> Each OpenStack project has an "API-source" folder containing RST files
>>>> describing its API structure ([2] for example). Those files are in turn
>>>> consumed by the Sphinx library to generate each project's API reference
>>>> manual which are then available in the API guide documentation [3]. Such
>>>> effort has made the APIs harmoniously consistent across all OpenStack
>>>> projects and has also created a "de-facto" API schema.
>>>>
>>>> While the RST files are used by the documentation, they are not readily
>>>> consumable by SDKs. Of course the APIs schema can be extracted by web
>>>> crawling the Reference guides, which in turn can be used by any
>>>> language. Such approach works [4] and help the Misty project [5] (Ruby
>>>> SDK) started with more languages to exploit the same approach.
>>>>
>>>> Therefore to allow better automation, the next step would be to have the
>>>> APIs schema stored directly into each project's repo so the SDKs could
>>>> consume them straight from the source. This is why we've started
>>>> discussing how to have the schema either extracted from the RST files or
>>>> alternatively having the API described directly into its own file. The
>>>> latter would provide a different work flow: "Yaml -> RST -> Reference
>>>> doco" instead of "RST -> Reference doco -> Yaml".
>>>>
>>>> So the question at this stage is: "Which of the work flow to choose
>>>> from?".
>>>>
>>>> To clarify the needs, it's important to note that we found out that none
>>>> of the SDKs project, besides OSC (OpenStack Client, thanks to Dean),
>>>> have full time working teams to maintain each SDK, which besides the
>>>> natural structural complexity inherent to the cloud context, makes the
>>>> task of keeping a SDK up to date very difficult. Especially as projects
>>>> moves forward. Automatically managing Openstack APIs is inevitable for
>>>> consumers. Another example/feedback was provided by the presenters of
>>>> "AT&T’s Strategy for Implementing a Next Generation OpenStack Cloud"
>>>> session during Sydney Keynotes, as they don't handle the Openstack API
>>>> manually!
>>>>
>>>> APIs consumers and providers, any thoughts?
>>>>
>>>> [1]
>>>> https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20442/api-sig-feedback-and-discussion-session
>>>>
>>>> [2] https://github.com/openstack/nova/tree/master/api-guide/source
>>>> [3] https://developer.openstack.org/api-guide/quick-start/index.html
>>>> [4] https://github.com/flystack/openstack-APIs
>>>> [5] https://github.com/flystack/misty
>>>>
>>>> Regards,
>>>> Gilles
>>> Please do not build something that looks like SOAP based on parsing RST
>>> files. Surely we can at least work directly from JSONSchema inputs?
>> I'm glad you said that :).
>> Working directly from YAML or JSON files (format to be discussed) to
>> maintain the schema seems (to me too) the natural approach.
>>
>> Meaning every project to change current practice: maintain the schema
>> files instead of maintaining RST files.
>> I suppose there has been suggestion to do it the other way (parse the
>> RST files) because of the latter impact on the current practice, but it
>> shouldn't be a blocker.
>>
>> Gil
>>
> When I was talking to Gil about it, I suggested writing a new sphinx /
> docutils formatter. I am not sure how feasible it would be, but it could
> be possible (as sphinx has the whole page tree in memory when writing it
> out, we may be able to output it in some sort of structured format.

That makes sense if the tree is already loaded, could you please provide 
a pointer?

>
> I would be hesitant to change how we write docs - this change took long
> enough to get in place, and the ability to add / remove bits to suit
> different projects is a good thing. Pages like [1] would be hard to do
> in a standard machine readable format, and I think they definitely make
> the docs better.

First off, let me insist: "The reference guides are absolutely great". I 
guess that's the ransom of the success! :)
So, from outside (as a blackbox) the doc generation process, it made 
sense to have a work flow going from a structured tree to the docs, 
meanwhile if the same information can be obtained from the existing that 
sounds good.

>
> - Graham
>
> 1 - https://developer.openstack.org/api-ref/compute/#servers-servers
>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-- 
Gil

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20171123/e1c132c8/attachment.html>