<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Title" content="">
<meta name="Keywords" content="">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:0 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.apple-tab-span
{mso-style-name:apple-tab-span;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:Calibri;
color:windowtext;}
span.msoIns
{mso-style-type:export-only;
mso-style-name:"";
text-decoration:underline;
color:teal;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body bgcolor="white" lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">... yeah forgot to mention the point that Ghada makes below,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">we currently use a very very out-dated approach to API Documentation ... i.e. Grizzly timeframe ... which uses maven and wadl files ... very ugly.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">This approach also had the API documentation centralized in one spot ... whereas now the API documentation seems to live (correctly) in the same git as the code.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">So we additionally need to convert our API Documentation to the current format being used for OpenStack API Doc and should distribute the API documentation appropriately to the appropriate
StarlingX sub-projects.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">Greg.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-family:Calibri;color:black">From: </span>
</b><span style="font-family:Calibri;color:black">"Khalil, Ghada" <Ghada.Khalil@windriver.com><br>
<b>Date: </b>Friday, August 3, 2018 at 6:41 PM<br>
<b>To: </b>"Jolliffe, Ian" <Ian.Jolliffe@windriver.com>, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com>, "starlingx-discuss@lists.starlingx.io" <starlingx-discuss@lists.starlingx.io><br>
<b>Cc: </b>Greg Waines <Greg.Waines@windriver.com><br>
<b>Subject: </b>RE: [Starlingx-discuss] StarlingX API Documentation<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Hi Abraham,<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">(You may know this already) The StarlingX APIs (especially for sysinv) are currently documented at:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><a href="https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc">https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">You can use the content as a starting point. However, the mechanism used is outdated using maven and wadl files. So you need to use the more current approach.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Greg Waines did some research on this. I strongly recommend you review with him when he's back from vacation (Tues Aug 7).<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Is this the story you are working on: <a href="https://storyboard.openstack.org/#!/story/2002712">
https://storyboard.openstack.org/#!/story/2002712</a> ? If so, I'll add some of the details Greg has captured to the story.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Regards,<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Ghada<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">-----Original Message-----<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">From: Jolliffe, Ian [<a href="mailto:Ian.Jolliffe@windriver.com">mailto:Ian.Jolliffe@windriver.com</a>]
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Sent: Friday, August 03, 2018 3:38 PM<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">To: Arce Moreno, Abraham; <a href="mailto:starlingx-discuss@lists.starlingx.io">
starlingx-discuss@lists.starlingx.io</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Subject: Re: [Starlingx-discuss] StarlingX API Documentation<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Hi Abraham;<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Thanks for kicking this off.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">On 2018-08-03, 12:40 PM, "Arce Moreno, Abraham" <<a href="mailto:abraham.arce.moreno@intel.com">abraham.arce.moreno@intel.com</a>> wrote:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal"> A new goal in collaboration with our Tech Writing team is to document StarlingX APIs,
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> so we did an initial research on what it means for StarlingX so your feedback is<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> highly appreciated.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <span class="apple-tab-span"> </span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [ OpenStack :: API ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> For this activity we are initially be considering from API Documentation 2 separate<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> efforts for each project:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - API Guide .. the concepts in the API<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - API Ref .. a reference for the API<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> Can we prioritize one over the other?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">We should do the concepts and the ref at the same time. The new OpenStack approach allows for tags to go in the code. Let's start with this work.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [ StarlingX :: API ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> It seems we can categorize the StarlingX APIs in 2:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - Brand New APIs from StarlingX projects<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - Existing APIs from OpenStack projects<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">StarlingX should not document other OpenStack API's, would their documentation not the source of truth?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [ StarlingX :: API :: Brand New ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> The projects falling into this category are the following:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - [0] NFVI Orchestration<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - [1] High Availability/Process Monitoring/Service Management<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - [2] StarlingX System Configuration Management<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - [3] Horizon plugins for new StarlingX services<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - [4] Installation/Update/Patching/Backup/Restore<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> Can we considered all the above to be included in this API documentation effort?
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> Are we missing any other?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">All projects in the Flock should be included. I think there is a dependency on some of the code restructuring activities that are underway, we need to make sure these activities don't collide. <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Ian<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [ StarlingX :: API :: Existing ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> All projects living under our starlingx-staging github organization [5] with<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> upstream contributions [6] e.g. horizon, ceilometer, etc.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> We have not gone through a deeper review if we are modifying/adding<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> new calls into the OpenStack projects however if we are and we need to document<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> them:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - There is official OpenStack <Project> API documentation, we can make references
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> to them for the existing calls<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - What about the modifications/additions? Should we document them?
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> What is the best place for this? We were talking in our weekly call about stx-docs<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> is a good place for things without a repo, is this a good example?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> - Any easy way besides "find + grep" to get where those API modifications are happening?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [ StarlingX :: API :: Unit Tests]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> OpenStack projects includes Unit Tests. Is this something we also need to consider<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> for our StarlingX Bran New APIs?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [0] <a href="http://git.openstack.org/cgit/openstack/stx-nfv/">
http://git.openstack.org/cgit/openstack/stx-nfv/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [1] <a href="http://git.openstack.org/cgit/openstack/stx-ha/">
http://git.openstack.org/cgit/openstack/stx-ha/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [2] <a href="http://git.openstack.org/cgit/openstack/stx-config/">
http://git.openstack.org/cgit/openstack/stx-config/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [3] <a href="http://git.openstack.org/cgit/openstack/stx-gui/">
http://git.openstack.org/cgit/openstack/stx-gui/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [4] <a href="http://git.openstack.org/cgit/openstack/stx-update/">
http://git.openstack.org/cgit/openstack/stx-update/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [5] <a href="https://github.com/starlingx-staging">https://github.com/starlingx-staging</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> [6] <a href="http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack">
http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> _______________________________________________<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> Starlingx-discuss mailing list<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <a href="mailto:Starlingx-discuss@lists.starlingx.io">Starlingx-discuss@lists.starlingx.io</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <a href="http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss">http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"> <o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">_______________________________________________<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">Starlingx-discuss mailing list<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><a href="mailto:Starlingx-discuss@lists.starlingx.io">Starlingx-discuss@lists.starlingx.io</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><a href="http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss">http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
</div>
</body>
</html>