<html xmlns:v="urn:schemas-microsoft-com:vml" 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="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
        {font-family:"Cambria Math";
        panose-1:2 4 5 3 5 4 6 3 2 4;}
@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","serif";}
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;
        font-family:"Calibri","sans-serif";
        color:windowtext;}
span.EmailStyle19
        {mso-style-type:personal;
        font-family:"Calibri","sans-serif";
        color:#1F497D;}
span.EmailStyle20
        {mso-style-type:personal-compose;
        font-family:"Calibri","sans-serif";
        color:windowtext;}
.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><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</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","sans-serif";color:#1F497D">Bruce/Abraham,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Can you target the completion of this work ( tracked via
<a href="https://storyboard.openstack.org/#!/story/2002712">https://storyboard.openstack.org/#!/story/2002712</a> ) in the August/early September time-frame?
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">I’ve tagged the Story for the stx.2018.10 release as I believe we want to have the API docs ready for the October release. Please let me know if you disagree.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Thanks,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Ghada<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<div>
<div style="border:none;border-top:solid #E1E1E1 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-size:11.0pt;font-family:"Calibri","sans-serif"">From:</span></b><span style="font-size:11.0pt;font-family:"Calibri","sans-serif""> Waines, Greg
<br>
<b>Sent:</b> Wednesday, August 08, 2018 7:33 AM<br>
<b>To:</b> Khalil, Ghada; Jolliffe, Ian; Arce Moreno, Abraham; starlingx-discuss@lists.starlingx.io<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>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif"">... 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","sans-serif"">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","sans-serif"">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","sans-serif""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif"">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","sans-serif""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif"">Greg.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif""><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","sans-serif";color:black">From:
</span></b><span style="font-family:"Calibri","sans-serif";color:black">"Khalil, Ghada" <<a href="mailto:Ghada.Khalil@windriver.com">Ghada.Khalil@windriver.com</a>><br>
<b>Date: </b>Friday, August 3, 2018 at 6:41 PM<br>
<b>To: </b>"Jolliffe, Ian" <<a href="mailto:Ian.Jolliffe@windriver.com">Ian.Jolliffe@windriver.com</a>>, "Arce Moreno, Abraham" <<a href="mailto:abraham.arce.moreno@intel.com">abraham.arce.moreno@intel.com</a>>, "<a href="mailto:starlingx-discuss@lists.starlingx.io">starlingx-discuss@lists.starlingx.io</a>"
 <<a href="mailto:starlingx-discuss@lists.starlingx.io">starlingx-discuss@lists.starlingx.io</a>><br>
<b>Cc: </b>Greg Waines <<a href="mailto:Greg.Waines@windriver.com">Greg.Waines@windriver.com</a>><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>