<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p><br>
</p>
<br>
<div class="moz-cite-prefix">On 23/11/17 07:04, Graham Hayes wrote:<br>
</div>
<blockquote type="cite"
cite="mid:258619eb-6980-d5c1-39d6-2bebacef3a4c@ham.ie">
<pre wrap="">
On 16/11/17 01:56, Gilles Dubreuil wrote:
</pre>
<blockquote type="cite">
<pre wrap="">
On 15/11/17 03:07, Doug Hellmann wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Excerpts from Gilles Dubreuil's message of 2017-11-14 10:15:02 +1100:
</pre>
<blockquote type="cite">
<pre wrap="">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]
<a class="moz-txt-link-freetext" href="https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20442/api-sig-feedback-and-discussion-session">https://www.openstack.org/summit/sydney-2017/summit-schedule/events/20442/api-sig-feedback-and-discussion-session</a>
[2] <a class="moz-txt-link-freetext" href="https://github.com/openstack/nova/tree/master/api-guide/source">https://github.com/openstack/nova/tree/master/api-guide/source</a>
[3] <a class="moz-txt-link-freetext" href="https://developer.openstack.org/api-guide/quick-start/index.html">https://developer.openstack.org/api-guide/quick-start/index.html</a>
[4] <a class="moz-txt-link-freetext" href="https://github.com/flystack/openstack-APIs">https://github.com/flystack/openstack-APIs</a>
[5] <a class="moz-txt-link-freetext" href="https://github.com/flystack/misty">https://github.com/flystack/misty</a>
Regards,
Gilles
</pre>
</blockquote>
<pre wrap="">Please do not build something that looks like SOAP based on parsing RST
files. Surely we can at least work directly from JSONSchema inputs?
</pre>
</blockquote>
<pre wrap="">
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
</pre>
</blockquote>
<pre wrap="">
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.</pre>
</blockquote>
<br>
That makes sense if the tree is already loaded, could you please
provide a pointer?<br>
<br>
<blockquote type="cite"
cite="mid:258619eb-6980-d5c1-39d6-2bebacef3a4c@ham.ie">
<pre wrap="">
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.</pre>
</blockquote>
<br>
First off, let me insist: "The reference guides are absolutely
great". I guess that's the ransom of the success! :)<br>
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. <br>
<br>
<blockquote type="cite"
cite="mid:258619eb-6980-d5c1-39d6-2bebacef3a4c@ham.ie">
<pre wrap="">
- Graham
1 - <a class="moz-txt-link-freetext" href="https://developer.openstack.org/api-ref/compute/#servers-servers">https://developer.openstack.org/api-ref/compute/#servers-servers</a>
</pre>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: <a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev-request@lists.openstack.org?subject:unsubscribe">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Gil
</pre>
</body>
</html>