[Starlingx-discuss] StarlingX API Documentation

Mon Aug 6 17:42:04 UTC 2018

Abraham, 

How are these built into documents?  I was playing around with the instructions in the README.mvn_cache file from my Ubuntu box and can't seem to create a mvn.repo.tgz following those steps.  

Scott

-----Original Message-----
From: Khalil, Ghada [mailto:Ghada.Khalil at windriver.com] 
Sent: Friday, August 3, 2018 3:42 PM
To: Jolliffe, Ian <Ian.Jolliffe at windriver.com>; Arce Moreno, Abraham <abraham.arce.moreno at intel.com>; starlingx-discuss at lists.starlingx.io
Subject: Re: [Starlingx-discuss] StarlingX API Documentation

Hi Abraham,

(You may know this already) The StarlingX APIs (especially for sysinv) are currently documented at:
https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc
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.

Greg Waines did some research on this. I strongly recommend you review with him when he's back from vacation (Tues Aug 7).

Is this the story you are working on: https://storyboard.openstack.org/#!/story/2002712 ? If so, I'll add some of the details Greg has captured to the story.

Regards,
Ghada

-----Original Message-----
From: Jolliffe, Ian [mailto:Ian.Jolliffe at windriver.com] 
Sent: Friday, August 03, 2018 3:38 PM
To: Arce Moreno, Abraham; starlingx-discuss at lists.starlingx.io
Subject: Re: [Starlingx-discuss] StarlingX API Documentation

Hi Abraham;

Thanks for kicking this off.

On 2018-08-03, 12:40 PM, "Arce Moreno, Abraham" <abraham.arce.moreno at intel.com> wrote:

    A new goal in collaboration with our Tech Writing team is to document StarlingX APIs, 
    so we did an initial research on what it means for StarlingX so your feedback is
    highly appreciated.

    [ OpenStack :: API ]

    For this activity we are initially be considering from API Documentation 2 separate
    efforts for each project:

      - API Guide .. the concepts in the API
      - API Ref .. a reference for the API

    Can we prioritize one over the other?

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.

    [ StarlingX :: API ]

    It seems we can categorize the StarlingX APIs in 2:

      - Brand New APIs from StarlingX projects
      - Existing APIs from OpenStack projects

StarlingX should not document other OpenStack API's, would their documentation not the source of truth?

    [ StarlingX :: API :: Brand New ]

    The projects falling into this category are the following:

      - [0] NFVI Orchestration
      - [1] High Availability/Process Monitoring/Service Management
      - [2] StarlingX System Configuration Management
      - [3] Horizon plugins for new StarlingX services
      - [4] Installation/Update/Patching/Backup/Restore

    Can we considered all the above to be included in this API documentation effort? 
    Are we missing any other?

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.  

Ian

    [ StarlingX :: API :: Existing ]

    All projects living under our starlingx-staging github organization [5] with
    upstream contributions [6] e.g. horizon, ceilometer, etc.

    We have not gone through a deeper review if we are modifying/adding
    new calls into the OpenStack projects however if we are and we need to document
    them:

    - There is official OpenStack <Project> API documentation, we can make references 
      to them for the existing calls
    - What about the modifications/additions? Should we document them? 
      What is the best place for this? We were talking in our weekly call about stx-docs
      is a good place for things without a repo, is this a good example?
    - Any easy way besides "find + grep" to get where those API modifications are happening?

    [ StarlingX :: API :: Unit Tests]

    OpenStack projects includes Unit Tests. Is this something we also need to consider
    for our StarlingX Bran New APIs?

    [0] http://git.openstack.org/cgit/openstack/stx-nfv/
    [1] http://git.openstack.org/cgit/openstack/stx-ha/
    [2] http://git.openstack.org/cgit/openstack/stx-config/
    [3] http://git.openstack.org/cgit/openstack/stx-gui/
    [4] http://git.openstack.org/cgit/openstack/stx-update/
    [5] https://github.com/starlingx-staging
    [6] http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack

    _______________________________________________
    Starlingx-discuss mailing list
    Starlingx-discuss at lists.starlingx.io
    http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss

_______________________________________________
Starlingx-discuss mailing list
Starlingx-discuss at lists.starlingx.io
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
_______________________________________________
Starlingx-discuss mailing list
Starlingx-discuss at lists.starlingx.io
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss